diff --git a/documentation/ToolGroups/index.md b/documentation/ToolGroups/index.md index c1f9939..dbc7488 100644 --- a/documentation/ToolGroups/index.md +++ b/documentation/ToolGroups/index.md @@ -29,10 +29,14 @@ 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 | +_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 @@ -62,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 { @@ -99,4 +108,4 @@ public class PlantingModeToolGroupConfigurator : IConfigurator containerDefinition.MultiBind().To().AsSingleton(); } } -``` \ No newline at end of file +``` 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 +``` 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.