From 69586fa3d31be8557f4ce0fbeb19d79a533b1e58 Mon Sep 17 00:00:00 2001 From: Igor Zavoychinskiy Date: Wed, 17 May 2023 01:33:15 -0700 Subject: [PATCH 1/5] Fix "fallbackgroup" issue --- documentation/ToolGroups/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/ToolGroups/index.md b/documentation/ToolGroups/index.md index c1f9939..48f7f90 100644 --- a/documentation/ToolGroups/index.md +++ b/documentation/ToolGroups/index.md @@ -29,6 +29,7 @@ ToolGroups are used to group multiple Tools together. | Order | - | Yes | Position of ToolButton | | Icon | - | Yes | Asset path to sprite | | NameLocKey | - | Yes | Localization key | +| FallbackGroup | - | Yes | Always set it to "false" | | DevMode | false | No | Required dev mode when true | | Hidden | false | No | Hides existing tool when true | | GroupInformation | - | Sometimes | Implementation defined data, check out the mod creator for this information | @@ -99,4 +100,4 @@ public class PlantingModeToolGroupConfigurator : IConfigurator containerDefinition.MultiBind().To().AsSingleton(); } } -``` \ No newline at end of file +``` From f3430418f2b94a0769a72f8db0eff6c6451891e0 Mon Sep 17 00:00:00 2001 From: Igor Zavoychinskiy Date: Wed, 17 May 2023 02:30:50 -0700 Subject: [PATCH 2/5] Explain tool group specification file name It's not obvious when you read through the docs that the file name is important. --- documentation/ToolGroups/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/documentation/ToolGroups/index.md b/documentation/ToolGroups/index.md index 48f7f90..c621fa1 100644 --- a/documentation/ToolGroups/index.md +++ b/documentation/ToolGroups/index.md @@ -34,6 +34,9 @@ ToolGroups are used to group multiple Tools together. | Hidden | false | No | Hides existing tool when true | | GroupInformation | - | Sometimes | Implementation defined data, check out the mod creator for this information | +_NOTE:_ The specification must be stored in a file with the specific name to be recognized properly. E.g. the file name can be `ToolGroupSpecification.foo.bar.original.json`, where prefix `ToolGroupSpecification`, suffix `original`, and extension `json` +are **required**. You can put arbitrary text between _prefix_ and _suffix_. See more in [specification naming](../specifications/index.md#specification-naming). + ### Example {: .no_toc } ```json From 2a94bacb76edf89a6ef324aaaf7ff22f1056078e Mon Sep 17 00:00:00 2001 From: Igor Zavoychinskiy Date: Wed, 17 May 2023 03:08:30 -0700 Subject: [PATCH 3/5] Explain the description behavior on the tool --- documentation/Tools/index.md | 44 ++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/documentation/Tools/index.md b/documentation/Tools/index.md index 10a27da..d86a032 100644 --- a/documentation/Tools/index.md +++ b/documentation/Tools/index.md @@ -20,19 +20,19 @@ For example placing buildings or prioritizing builders. ## ToolSpecification Scheme -| Property | Default | Required | Description | -|-------------------|---------|-----------|-----------------------------------------------------------------------------| -| Id | - | Yes | Unique identifier | -| GroupId | - | No | Group unique identifier | +| Property | Default | Required | Description | +|-------------------|---------|-----------|----------------------------------------------------------------------------------------------------------------------| +| Id | - | Yes | Unique identifier | +| GroupId | - | No | Group unique identifier | | Type | - | Yes | Defines what tool will be created, check out [TimberApi Tools](https://github.com/Timberborn-Modding-Central/TimberAPI/tree/main/Core/TimberApi/ToolSystem/Tools) to find the identifiers or check out the mod creator | -| Layout | Brown | No | Defines what button layout will be created | -| Order | - | Yes | Position of ToolButton | -| Icon | - | Yes | Asset path to sprite | -| NameLocKey | - | Yes | Localization key | -| DescriptionLocKey | - | Yes | Localization key | -| DevMode | false | No | Required dev mode when true | -| Hidden | false | No | Hides existing tool when true | -| ToolInformation | - | Sometimes | Implementation defined data, check out the mod creator for this information | +| Layout | Brown | No | Defines what button layout will be created | +| Order | - | Yes | Position of ToolButton | +| Icon | - | Yes | Asset path to sprite | +| NameLocKey | - | Yes | Localization key | +| DescriptionLocKey | - | Yes | Localization key. Even though it's required, it will _not_ be used "out of the box". Your code must take care of it. | +| DevMode | false | No | Required dev mode when true | +| Hidden | false | No | Hides existing tool when true | +| ToolInformation | - | Sometimes | Implementation defined data, check out the mod creator for this information | ### Example {: .no_toc } @@ -67,6 +67,21 @@ When creating a Tool the original method of Timberborn does not work! Follow the ### Example {: .no_toc } ```csharp +public class CancelPlantingTool : Tool +{ + public CancelPlantingTool(ToolGroup toolGroup) + { + ToolGroup = toolGroup; + } + + public override ToolDescription Description() + { + // Here you make the actual tooltip. Return `null` if you don't want a tooltip. + return new ToolDescription.Builder().Build(); + } +} +``` +```csharp public class CancelPlantingToolFactory : IToolFactory { ... @@ -75,7 +90,8 @@ public class CancelPlantingToolFactory : IToolFactory public Tool Create(ToolSpecification toolSpecification, ToolGroup? toolGroup = null) { - return new CancelPlantingTool(_plantingSelectionService, toolGroup); + // Handle `toolSpecification` eher or pass it down to the tool. + return new CancelPlantingTool(toolGroup); } } ``` @@ -142,4 +158,4 @@ public class CancelPlantingToolConfigurator : IConfigurator containerDefinition.MultiBind().To().AsSingleton(); } } -``` \ No newline at end of file +``` From f104584d078b6c7c249387d95368af7232d95d1a Mon Sep 17 00:00:00 2001 From: Igor Zavoychinskiy Date: Wed, 17 May 2023 18:04:21 -0700 Subject: [PATCH 4/5] Explain specification file name more formally --- documentation/specifications/index.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/documentation/specifications/index.md b/documentation/specifications/index.md index 5902a7d..f4fc69f 100644 --- a/documentation/specifications/index.md +++ b/documentation/specifications/index.md @@ -19,7 +19,22 @@ Specifications have a large range of usage. For example, you can make new or edi Factions, Goods, Needs, Recipes and more. The specifications are automatically loaded within the specification folder relative to your mod location. You can place any sub folder inside the specification folder, all sub folders will be ignored. -## Specification usage +The name of the specification definition file tells how the specifiaction must be handled and applied. The format is the following: + +```backus-naur-form + ::= "Specification." ".json" + ::= "replace." | "original." | "" +``` + +where: +* `` is one of the types described in [timberborn schemas](../specifications/schemas.md). +* `` indicates how the specification should be applied: + * By default, the file content will be merged with the existing specifcation. The array fields will be expanded. If there is no specification exist already, then no changes will be made. + * `replace` is a variation of the default behavior, but teh array fields will be complete replaced instead of expanding with new values. + * `original` indicates that it's a completely new specification that will become available for others to overwrite. +* `` addresses a specific definition within the type. E.g. for type `Good` it's the name of the specifc good being overwritten. + +## Specification usage example In the following sections we will show you examples how you can use the specification system. For all examples we are using the good specification of berries. @@ -52,11 +67,10 @@ For all examples we are using the good specification of berries. ## Specification naming In this section we are going to look how the file naming is setup for `GoodSpecification.Berries.json` Let's split this up: -- `Good` Specification type -- `Specification` Specifies that it is a specification -- `.Berries` The name of the good -- `.json` File extension - +- `Good` Specification type (``). +- `Specification.` Indicates that it is a specification. +- `Berries` The name of the good (``). +- `.json` File extension. ### overwrite Timberborn or custom specifications The default behaviour is to merge any original specification with the same name. From 20e777843a0c0cfd0432480972bc865dbffae52c Mon Sep 17 00:00:00 2001 From: Igor Zavoychinskiy Date: Wed, 17 May 2023 18:21:41 -0700 Subject: [PATCH 5/5] Explain group tool class definition Explain that a dedicated class it's not absolutely required. It depends on the specific group requirements and behavior. --- documentation/ToolGroups/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/documentation/ToolGroups/index.md b/documentation/ToolGroups/index.md index c621fa1..dbc7488 100644 --- a/documentation/ToolGroups/index.md +++ b/documentation/ToolGroups/index.md @@ -66,6 +66,11 @@ When creating a Tool the original method of Timberborn does not work! Follow the ### Example {: .no_toc } + +The specialized class `PlantingModeToolGroup` is reqired because a special behavior is needed on the tool selection. It's done by +implementing `IPlantingToolGroup`. If it was a trivial case, it would be enough to provide an instance of plain `ApiToolGroup` from +the factory. + ```csharp public class PlantingModeToolGroup : ApiToolGroup, IPlantingToolGroup {