Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Various fixes to the tool/group section #21

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
+60 −21
Draft

Various fixes to the tool/group section #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
69586fa
Fix "fallbackgroup" issue
ihsoft May 17, 2023
f343041
Explain tool group specification file name
ihsoft May 17, 2023
2a94bac
Explain the description behavior on the tool
ihsoft May 17, 2023
f104584
Explain specification file name more formally
ihsoft May 18, 2023
20e7778
Explain group tool class definition
ihsoft May 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion documentation/ToolGroups/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
{
Expand Down Expand Up @@ -99,4 +108,4 @@ public class PlantingModeToolGroupConfigurator : IConfigurator
containerDefinition.MultiBind<IToolGroupFactory>().To<PlantingModeToolGroupFactory>().AsSingleton();
}
}
```
```
44 changes: 30 additions & 14 deletions documentation/Tools/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand Down Expand Up @@ -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
{
...
Expand All @@ -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);
}
}
```
Expand Down Expand Up @@ -142,4 +158,4 @@ public class CancelPlantingToolConfigurator : IConfigurator
containerDefinition.MultiBind<IToolFactory>().To<PlaceableObjectToolFactory>().AsSingleton();
}
}
```
```
26 changes: 20 additions & 6 deletions documentation/specifications/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<filename> ::= <specification-type> "Specification." <item-name> <opt-behavior> ".json"
<opt-behavior> ::= "replace." | "original." | ""
```

where:
* `<specification-type>` is one of the types described in [timberborn schemas](../specifications/schemas.md).
* `<opt-behavior>` 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.
* `<item-name>` 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.

Expand Down Expand Up @@ -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-type>`).
- `Specification.` Indicates that it is a specification.
- `Berries` The name of the good (`<item-name>`).
- `.json` File extension.

### overwrite Timberborn or custom specifications
The default behaviour is to merge any original specification with the same name.
Expand Down