document the encyclopedia format

1 files changed, 114 insertions, 0 deletions

diff --git a/docs/encyclopedia_format.md b/docs/encyclopedia_format.md
new file mode 100644
index 0000000..5c8a7b2
--- /dev/null
+++ b/docs/encyclopedia_format.md
@@ -0,0 +1,114 @@
+
+# Encyclopedia
+
+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.
+
+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.
+"assemblages" is a dict of assemblages and "items" is a dict of items.
+The keys can be the same, but by default the items dict will automatically insert an assemblage of the same name in the assemblages dict.
+
+## Assemblage
+
+An assemblage is a type/blueprint of game object.
+The assemblage can be futher customized using the given arguments.
+
+There are 3 main properties of an assemblage: "components", "arguments", "save" and "extract".
+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 component parameters.
+
+Example:
+
+	"wall": {
+		"components": [
+			["Visible", {
+				"sprite": "wall",
+				"height": 0.1,
+				"name": "wall"
+			}],
+			["Flags", {
+				"flags": ["list", ["Blocking"]]
+			}]
+		]
+	}
+
+Note: technically the encyclopedia key (`"wall":`) part is not part of the assemblage definition.
+
+The Flags and Visible components are so common that there is a shortcut for defining them.
+If the assemblage has a "sprite" property and a "height" property then in preprocessing a Visible component will be added.
+A "name" property is optional for the shortcut and will default to the sprite name (this might change to default to the key in the encyclopedia).
+The Flags component will automatically be added if the "flags" poperty is on the assemblage.
+
+The example above can be shortened to this:
+
+	"wall": {
+		"sprite": "wall",
+		"height": 2,
+		"flags": ["Blocking"]
+	}
+
+For a full list of components and what type of parameters they take, see: https://github.com/jmdejong/rustifarm/blob/master/src/componentwrapper.rs (lower part of the file)
+
+### Arguments
+
+An assemblage can be constructed with a template.
+This template can provide the assemblage with arguments.
+The argments are a list of lists of 2 or 3 items.
+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" component parameter 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"]}]
+		],
+		"flags": ["Floor"]
+	}
+
+Arguments (and other component parameters) 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.
+
+
+### 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 component parameter 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 component parameters currently occur is as parameters to components.
+
+Possible component parameters:
+
+- arg (argument: string): take the actual value from the assemblage argument that is named by the argument of this component parameter
+- random (argument: list of component parameters): pick a random value from its arguments. All argument items must have the same type.
+- concat (argument: list of component parameters): concatenate the string value of its arguments. All argument items must be of type string.
+- if (argument: list of 3 component parameters: 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.
+
+### Save
+
+If the "save" property is not present in an assemblage, when construction the entity a serialize component will be added automatically unless the template specifies that it should not be saved (automatically the case for all entities added from the map file).
+If this is set to false the entity is never saved.
+If this is set to true the entity is always saved, even when the template says it shouldn't save.
+