.

buildserver/configurator/README.md

@@ -1,40 +1,34 @@
 # configurator
 
-helper for generating json configs interactively.
-Plugins that hook into this plugin can register configuration nodes like "lobby.spawnpoint" with type Location.
-server operators can then go ingame and do `/cfg key lobby.spawnpoint` to set a spawn location and then
-`/cfg export` ig
+This plugin/API allows developers to define configuration fields by name(or rather key) and data type, and have admins easily set
+the fields' values in-game using commands such as `/cfg key chat.messageDelay set 50 ms`.
 
-## TODO
+<small>
+the key literal in `/cfg key` is required, because there are other modes like `/cfg check` that checks
+the config for uninitialized values.
+</small>
 
-- lists
-- exporting
-- proper namespaces
-- split into api and impl
-- more types(region pickers especially; also itemstacks)
-- type variants like location without yaw/pitch
+# Design
 
-## design
+Plugins register configuration nodes by key. A key consists of a unique identifier and a type.
+The type handles (de)serialization and defines actions. Actions can be used on nodes.
+Nodes hold values.
 
-in json we have primitives(like "hi", 1, false"), structures(like {"foo":"bar}) and lists(like []).
-everything consists of primitives eventually so we can go from
+The `/config` or `/cfg` command is used by admins to configure the plugin:
+A lobby plugin might register a node with the identifier `lobby.spawnLocation` and type `ConfigLocationType`,
+which gives us the command `/cfg key lobby.spawnLocation`.
+Let's say the ConfigLocationType defines an action to use the player's location as the value("pick-current")
+and an action to teleport the user to the defined location("teleport").
+Thus, we can do `/cfg key lobby.spawnLocation pick-current` or `/cfg key lobby.spawnLocation teleport`.
+Tab completion makes this pretty obvious.
 
-```json
-{
-  "arenas": [
-    {
-      "name": "skyfall",
-      "minPlayers": 3,
-      "maxPlayers": 8
-    }
-  ]
-}
-```
-to
-```text
-arenas.0.name = Primitive("skyfall")
-arenas.0.minPlayers = Primitive(3)
-arenas.0.maxPlayers = Primitive(8)
-```
+## Lists
 
-We can define a complex type as "type has a string field called name" and it will just use 
+Now maybe we want to make our lobby have some launch pads(i.e. some pressure plates that launch the player).
+So, lists would be handy.
+For lists, we simply use a Node of type List<ConfigType of Element>, so for our launch pads, we could make a node
+with identifier "lobby.launchpads" and type `ConfigListType<ConfigLocationType>`.
+Now to add a launch pad, we can just `/cfg key lobby.launchpads append`, which creates a new uninitialized element
+in the list, followed by `/cfg key lobby.launchpads.0 pick-current` which actually sets the node's value.
+
+The node `lobby.launchpads.0` is not a real registered node. It is a Sub-Node of the `lobby.launchpads` node.