diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/encyclopedia_format.md | 62 | ||||
| -rw-r--r-- | docs/glossary.md | 2 | ||||
| -rw-r--r-- | docs/map_format.md | 25 |
3 files changed, 41 insertions, 48 deletions
diff --git a/docs/encyclopedia_format.md b/docs/encyclopedia_format.md index 01d21e5..52ff7e9 100644 --- a/docs/encyclopedia_format.md +++ b/docs/encyclopedia_format.md @@ -3,7 +3,9 @@ In asciifarm all the assemblages and items are stored in an encyclopedia. -see https://github.com/jmdejong/rustifarm/blob/master/content/encyclopediae/default_encyclopedia.json for an example. +See https://github.com/jmdejong/rustifarm/blob/master/content/encyclopediae/default_encyclopedia.json for an example. + +Encyclopediae definitions can use the [JSON5](https://json5.org/) format. An encyclopedia file has a json object that can have the properties "assemblages", "items", "substitute", "item_substitute" and "assemblage_substitute". "assemblages" and "items" are required. @@ -21,7 +23,7 @@ All other properties are just shortcuts. ### Components "components" is the most important property. This is a list. -The items of the list are a list of 2 items: The component name (as a string) and a dict of componentparameters. +The items of the list are a list of 2 items: The component name (as a string) and a dict of ParameterExpressions. Example: @@ -33,7 +35,7 @@ Example: "name": "wall" }], ["Flags", { - "flags": ["list", ["Blocking"]] + "flags": ["Blocking"] }] ] } @@ -64,19 +66,19 @@ The first item is the name (as string). The second item is the parameter type (as string). The optional third item is the default value. -An "args" componentparameter in the component definitions will have its value filled in with the value that is given to this argument, or otherwise the default value (and if that doesn't exist either it will error). +An "args" ParameterExpression in the component definitions will have its value filled in with the value that is given to this argument, or otherwise the default value (and if that doesn't exist either it will error). Example: "portal": { "arguments": [["destination", "string"], ["destpos", "string", ""]], "components": [ - ["RoomExit", {"destination": ["arg", "destination"], "dest_pos": ["arg", "destpos"]}] + ["RoomExit", {"destination": {"$arg": "destination"}, "dest_pos": {"$arg": "destpos"}}] ], "flags": ["Floor"] } -Arguments (and other componentparameters) can not be used within shortcuts, so if you want to set the sprite by argument you'll have to add the Visible component manually. +Arguments (and other ParameterExpressions) can not be used within shortcuts, so if you want to set the sprite by argument you'll have to add the Visible component manually. ### Save @@ -104,14 +106,14 @@ Example: "builtwall": { "arguments": [["health", "int", 100]], "components": [ - ["Health", {"health": ["arg", "health"], "maxhealth": 100}], - ["Loot", {"loot": ["list", [{"type": "stone"}]]}] + ["Health", {"health": {"$arg": "health"}, "maxhealth": 100}], + ["Loot", {"loot": [[{"$template": "stone"}, 1.0]]}] ], "sprite": "builtwall", "height": 2, "extract": {"health": ["Health", "health"]}, "flags": ["Blocking"] - } + }, ## Items @@ -134,29 +136,25 @@ The values are again a json dict that can have the following properties: # Used concepts ## Parameter -A parameter can be a string, an integer, a float, a boolean, a list, a pos, a template or an interaction. -The specific type can be given explicitly by giving a list of 2 elements: the first is the type (as string), the second the actual value. -For example: `["int", 3]`. -For integers, floats and booleans the type can be derived from the json value. -Templates need to be in the object form or with explicit type annotation because they would otherwise be seen as strings. -Lists always need the type annotation. -For example a list of pairs of a template and a float would look like this: `["list", [["list", [{"type": "carrotseed"}, 1.0]],["list", [{"type": "carrot"}, 1.0]]]]` -Interactions (which also alway need type annotation) are a json list of 2 values: The interaction type (string) and the argument. -The type of the argument value can differ based on the interaction type. -todo: list interaction types with description what they do and their arguments. - -## ComponentParameter - -A componentparameter is either a parameter, or a special function. -The special functions are given in the same way as the type annotations of a parameter, so as a pair of the type of function (as string) and its argument. -The only place where componentparameters currently occur is as parameters to components. +A parameter can be a string, an integer, a float, a boolean, a list, or a template. +Most types map directoy to the corresponding json type. +A template is a json object that has a `:template` field. +The entity type is the value of that field. +Other arguments are passed in the same object. -Possible componentparameters: -- arg (argument: string): take the actual value from the assemblage argument that is named by the argument of this componentparameter -- random (argument: list of componentparameters): pick a random value from its arguments. All argument items must have the same type. -- concat (argument: list of componentparameters): concatenate the string value of its arguments. All argument items must be of type string. -- if (argument: list of 3 componentparameters: condition, thenpart, elsepart) if the condition evaluates to true, take the value of thenpart, otherwise take the value of elsepart. The condition must be of type bool, and the thenpart and elsepart must have the same type. -- self (does not use its argument): the template given to the assemblage used to construct this pre-entity. -- name (does not use its argument): the name of the assemblage in the encyclopedia. +## ParameterExpression + +A ParameterExpression is either a parameter, or a special function. +The special functions are given in the same way as the type annotations of a parameter, so as a pair of the type of function (as string) and its argument. +The only place where ParameterExpressions currently occur is as parameters to components. + +Possible ParameterExpressions: +- `$arg` (argument: string): take the actual value from the assemblage argument that is named by the argument of this ParameterExpression. +- `$template` (argument: entity type; also takes all other properties as parameters to the template). A Constructor for a template. The difference between a `:template` object and a `$template` object is that `:template` objects can only use constants as their parameters, while `$template` objects can have expressions in their parameters. +- `$random` (argument: list of ParameterExpressions): pick a random value from its arguments. All argument items must have the same type. +- `$concat` (argument: list of ParameterExpressions): concatenate the string value of its arguments. All argument items must be of type string. +- `$if` (argument: list of 3 ParameterExpressions: condition, thenpart, elsepart) if the condition evaluates to true, take the value of thenpart, otherwise take the value of elsepart. The condition must be of type bool, and the thenpart and elsepart must have the same type. +- `$self` (does not use its argument): the template given to the assemblage used to construct this pre-entity. +- `$name` (does not use its argument): the name of the assemblage in the encyclopedia. diff --git a/docs/glossary.md b/docs/glossary.md index fb3323d..f74f8b1 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -34,7 +34,7 @@ Something that exists in the player inventory. Usually this also corresponds to ## Parameter -A layer between JSON and the datastructures in the rustifarm code. Can be int, float, bool, string, template, list and interaction. The interaction parameter is in the process of being deprecated. +A layer between JSON and the datastructures in the rustifarm code. Can be int, float, bool, string, template or list. ## ComponentParameter diff --git a/docs/map_format.md b/docs/map_format.md index 57d46eb..aa44276 100644 --- a/docs/map_format.md +++ b/docs/map_format.md @@ -11,17 +11,12 @@ This object has several properties: - field (list of strings): Indicates what kind of tile each location should have. The kind of tile is denoted with a single character (can be any unicode character) that can be looked up in the mapping. The list should be as long as the height, and each string should be as long as the width (though it will be cut off or filled in with empty tiles if it is too long or short). - mapping (json dict): A dictionary that denotes what each character in the field corresponds to. The key is a single character. The value is either a template or a list of templates. -A template is either a string, or a json object with at least the property "type" (a string) and possibly the properties "args" (a list of parameters) and "kwargs" (a json dict of parameters). The usage of "args" is discouraged. +A template is either a string, or a json object with at least the property ":template" (a string, referring to the entity type). +The other properties are parameters belonging to that template -The following templates are equivalent: `"grass"`, `{"type": "grass"}`, `{"type": "grass", "args": [], "kwargs": {}}` +The following templates are equivalent: `"grass"`, `{":template": "grass"}` -A parameter can be a string, an integer, a float, a boolean, a list (not the same as a json list) or a template. -The specific type can be given explicitly by giving a list of 2 elements: the first is the type (as string), the second the actual value. -For example: `["int", 3]`. -For integers, floats and booleans the type can be derived from the json value. -Templates need to be in the object form or with explicit type annotation because they would otherwise be seen as strings. -Lists always need the type annotation. -For example a list of pairs of a template and a float would look like this: `["list", [["list", [{"type": "carrotseed"}, 1.0]],["list", [{"type": "carrot"}, 1.0]]]]` +A parameter can be a string, an integer, a float, a boolean, a list or a template. The type of a template refers to an assemblage in the encyclopedia. The args and kwargs of the template are arguments to that assemblage. @@ -71,13 +66,13 @@ The encyclopedia has to be checked to see what arguments an assemblage uses and "T": ["grass", "tree"], "f": ["grass", "fence"], "X": "rock", - "*": ["grass", {"type": "spawner", "kwargs": {"template": {"type": "pebble"}, "delay": 1200, "initial_spawn": false}}], - "o": ["grass", {"type": "spawner", "kwargs": {"template": {"type": "stone"}, "delay": 1200, "initial_spawn": false}}], - "%": {"type": "portal", "kwargs": {"destination": "broom", "destpos": "northentry"}}, - "1": {"type": "portal", "kwargs": {"destination": "smallview"}}, + "*": ["grass", {":template": "spawner", "template": {":template": "pebble"}, "delay": 1200, "initial_spawn": false}], + "o": ["grass", {":template": "spawner", "template": {":template": "stone"}, "delay": 1200, "initial_spawn": false}], + "%": {":template": "portal", "destination": "broom", "destpos": "northentry"}, + "1": {":template": "portal", "destination": "smallview"}, "^": ["grass", "spiketrap"], - "d": ["grass", {"type": "spawner", "kwargs": {"template": {"type": "dummy"}, "delay": 100, "initial_spawn": true}}], - "r": ["grass", {"type": "spawner", "kwargs": {"template": {"type": "rat"}, "amount": 3, "clan": "rats", "delay": 200, "initial_spawn": true}}], + "d": ["grass", {":template": "spawner", "template": {":template": "dummy"}, "delay": 100, "initial_spawn": true}], + "r": ["grass", {":template": "spawner", "template": {":template": "rat"}, "amount": 3, "clan": "rats", "delay": 200, "initial_spawn": true}], "V": ["grass", "radishplant"], "/": ["grass", "sword"], "D": ["ground", "closeddoor"], |