Add some new docs

docs/hammerstone/ddapi/ddapi-config-types.md

@@ -0,0 +1,71 @@
+# DDAPI Config Types
+
+## Object
+
+Objects are defined within `hammerstone/objects/*.json`.
+
+Schema: `"$schema": "https://raw.githubusercontent.com/Sapiens-OSS/hammerstone-schemas/main/schemas/object.schema.json"`
+
+Example:
+
+```json
+{
+	"hammerstone:object_definition": {
+		"description": {
+			"identifier": "apple"
+		},
+		"components": {
+			...
+		}
+	}
+}
+```
+
+## Storage
+
+Storages are defined within `hammerstone/storage/*.json`
+
+Schema:
+
+Example:
+
+```json
+{
+    "hammerstone:storage_definition": {
+        "description": {
+            "identifier": "apple_storage"
+        },
+        "components": {
+            ...
+        }
+    }
+}
+```
+
+## Shared Config
+
+Shared configs are files that define lots of small definitions. You can split them into multiple files, or combine them.
+
+Shared configs are defined within `hammerstone/shared/*.json`
+
+Example:
+
+```json
+{
+    "hammerstone:global_definitions": {
+		"hs_seat_types": [
+			...
+		],
+		"hs_model_remaps": [
+			...
+		],
+		"hs_materials": [
+			...
+		]
+	}
+}
+```
+
+## Builders
+
+Builders are lua-only files defined in `hammerstone/builders/*.lua`. They are explained further in [lua builders.](./ddapi-lua-builders.md)

docs/hammerstone/ddapi/ddapi-getting-started.md

@@ -2,21 +2,29 @@
 
 The 'DDAPI' is a data-driven API for creating Hammerstone mods: rather than working with the games code directly, you're instead authoring a "config" format which Hammerstone interprets.
 
+## Config Types
 
-Writing config files can be done in two formats: Lua and JSON. 
-Both are fully supported, yet the differences are that the json file has a light additional wrapper layer on the outside and a web editor;
- while Lua can add logic inside (useful for defining a template for instance).
+Writing config files can be done in two formats: Lua and JSON. Both are fully supported, yet come with some unique trade-offs. Unless stated otherwise, DDAPI examples use the JSON format.
 
-Unless stated otherwise, DDAPI examples use the JSON format.
+### JSON
 
-### Philosophy
+JSON is the default config format, and the first format that Hammerstone supported. All examples will use JSON. JSON is good when you want to do something simple, and want maximum editor help in defining the config files. A json schema is available, so you can get autocomplete in your editor of choice (e.g., VSCode).
+
+### Lua
+
+Lua configs were added later, when it became clear that JSON configs aren't suitable for all use-cases. Namely, in complex scenarios where you want to write lua code inline as part of the configs. For example, generating multiple items from the same bit of code, or doing some inline maths calculations.
+
+Lua is best suited when you know what you're doing, or you're trying to accomplish something very unique.
+
+## Philosophy
 
 In the base game of Sapiens, the data and logic for a "feature" is often spread across multiple files. For example, to create an apple, you might need the following:
- - `gameObject.lua` - Define the apple object
- - `resource.lua` - Give it a 'resource' definition for storage/crafting
- - `evolvingObject.lua` - Allow the apple to 'rot' away, or into a rotten variant
- - `storage.lua` - Allow the apple to be carried and stored in storage areas
- - ... and more!
+
+- `gameObject.lua` - Define the apple object
+- `resource.lua` - Give it a 'resource' definition for storage/crafting
+- `evolvingObject.lua` - Allow the apple to 'rot' away, or into a rotten variant
+- `storage.lua` - Allow the apple to be carried and stored in storage areas
+- ... and more!
 
 With Hammerstone, we reverse this relationship. We believe you should be able to define your data in a single place, with a well-defined API. To create
 an apple in Hammerstone, you would only need to create `apple.json`.
@@ -33,18 +41,9 @@ Inside this apple file, you define "components" describing the apple. For exampl
 }
 ```
 
-
-### Config Types
-
-At it's core, Hammerstone is a *json based API*. The reason we chose json is because it's a data-exchange format. That means there are a lot of tools like json schemas which
-we can leverage. If you use our schemas you can get in-editor autocomplete, documentation, tool-tips, and linting.
-
-However json isn't the best for complex items, which might require some programmatic-handling. In these cases you can also define your items in lua. We will read these lua files and evaluate them
-as such.
-
 # Getting Started with DDAPI
 
-To get started, you need a live copy of Hammerstone beta, and a text editor like VSCode. Then create a folder structure like this:
+To get started, you need a live copy of Hammerstone, and a text editor like VSCode. Then create a folder structure like this:
 
 ```
 mod-name
@@ -54,4 +53,4 @@ mod-name
 			my_object.json
 ```
 
-	
+Read further in the [DDAPI Object Guide](./ddapi-objects.md)

docs/hammerstone/ddapi/ddapi-lua-builders.md

@@ -0,0 +1,25 @@
+# Lua Builders
+
+Builders are a hybrid approach between normal modding, and config driven modding. Instead of defining each config in it's own file, builders allow you to create lots of definitions at once, all from a single file. This is possible via defining a Lua module that defines an "interface" of functions. Hammerstone will call these functions automatically, and interpret the list of results as objects to create via Hammerstone. Builders are useful when you want to generate lots of similar objects, or need more programatic control.
+
+## Define a Builder
+
+`builders` are defined inside of `hammerstone/builders/*.lua`. Unlike all other config files, they MUST be defined in lua -not json.
+
+## Format of a Builder
+
+The base file will look something like this:
+
+```lua
+local gen = {}
+return gen
+```
+
+In other words, its a totally normal module. The trick is you need to define some (optional) functions. These are:
+
+- `getObjectConfigs()`
+- `getMaterials()`
+- `getModelRemaps()`
+- `getResourceGroups()`
+
+The return result should be a list of valid ddapi configs.

docs/hammerstone/ddapi/ddapi-lua-configs.md

@@ -0,0 +1,50 @@
+# Lua Configs
+
+Often, when writing Hammerstone DDAPI mods, you might find the json-based API limiting, or annoying to use. In that case, use lua! You can write 1:1 the same configs, except just do it in lua instead.
+
+Example (truncated):
+
+```lua
+local data = mjrequire "furniture/data"
+
+return {
+	description = {
+		identifier = "chair"
+	},
+	components = {
+		hs_object = {
+			model = "chair"
+		},
+		hs_buildable = {
+			skill = "woodBuilding",
+			build_sequence = "clearObjectsAndTerrainSequence",
+			...
+		}
+	}
+}
+```
+
+## Why Lua?
+
+One of the biggest reasons to use Lua is to use the [lua builder](./ddapi-lua-builders.md) format to generate lots of actors programatically. There are other reasons though as well, such as a preference for the syntax, or inline calculations.
+
+## Props
+
+When using Lua, the `props` field can be used to define some lua data that will be 1:1 copied to the base game object. For example, imagine you're creating an object in which `preventShiftOnTerrainSurfaceModification` MUST be true. This isn't something we bothered to add to the DDAPI yet, so by default, you're blocked.
+
+`props` is the safety hatch. Simple define it like this:
+
+```lua
+hs_object = {
+	model = "chair",
+	props = {
+		preventShiftOnTerrainSurfaceModification = true
+	}
+},
+```
+
+The results of the `props` will be moved into the object when it's created.
+
+`props` is allowed in other places as well. For example, when defined inside of the `hs_evolving_object`, the `props` field will move that lua code into the evolving object definition. Same for resources, storage, craftables, etc.
+
+If you're ever perusing a long list of objects in the base game code (e.g., `gameObject.lua`), and see a field you want to insert into your config, add it via `props`

docs/hammerstone/ddapi/ddapi-objects.md

@@ -2,9 +2,13 @@
 
 Objects can be created by defining a config file in `mod/hammerstone/objects/<name>.json`
 
+::: tip Use Cheats
+When testing your mods, it's very useful if you can quickly inspect and cheat in items. Since you've already started using Hammerstone, you might as well pull in [Creative Mode](https://github.com/SirLich/sapiens-creative-mode) as well for development.
+:::
+
 ## Hello World example
 
-Here is a simple example which creates a linked `resource` and `object`. It references base-game models, so you can safely copy/paste.
+Here is a simple example which creates a linked `resource` and `object`. It references base-game models, so you can safely copy/paste directly into your mod. After adding this file, the new item should appear in game.
 
 This will create a new item called `coconut_2`, which you can spawn and decorate with. It can be picked up and stored with the other coconuts (link to storage), but
 it has no other behaviors (cannot be eaten, or rot, or crafted with).
@@ -20,7 +24,7 @@ it has no other behaviors (cannot be eaten, or rot, or crafted with).
         "model": "coconut"
       },
       "hs_resource": {
-        "link_to_storage": "coconut"
+        "storage_identifier": "coconut"
       }
     }
   }
@@ -53,4 +57,5 @@ Here is a quick refresher:
 - Can be crafted with (i.e., you don't craft with a `birchBranch` you craft with a `branch` -the game figures the rest out)
 
 ## Schema
+
 Refer to the [JSON schema](https://github.com/Sapiens-OSS/hammerstone-schemas/blob/main/schemas/object.schema.json) for all the possible values.

docs/hammerstone/ddapi/ddapi-remaps.md

@@ -1,6 +1,6 @@
 # DDAPI Remaps
 
-This page provides Hammerstone alternatives to shadowing base lua files. If a file isn't listed here, you likely need to 
+This page provides Hammerstone alternatives to shadowing base lua files. If a file isn't listed here, you likely need to
 create it, shadow it, and interact with Sapiens base code normally.
 
 ### gameObject.lua
@@ -20,7 +20,7 @@ Hammerstone: `hammerstone:object_definition/hs_resource`
 A craftable is a "recipe" for creating new game objects by combining or working with other game objects. For example you can craft 'campfireRoastedBeetroot'
 by roasting beets at a campfire.
 
-Hammerstone: `hammerstone:recipe_definition`
+Hammerstone: `hammerstone:object_definition/hs_craftable`
 
 ### evolvingObject.lua
 
@@ -31,7 +31,7 @@ Hammerstone: `hammerstone:object_definition/hs_evolving_object`
 
 ### harvestable.lua
 
-Harvestables are in-game objects which can be "harvested" for resources. The most common example would be animal carcases. 
+Harvestables are in-game objects which can be "harvested" for resources. The most common example would be animal carcases.
 
 Hammerstone: `hammerstone:object_definition/hs_harvestable`
 
@@ -50,5 +50,6 @@ Hammerstone: `hammerstone:global_definitions/hs_object_sets`
 ## No Remaps
 
 These files don't currently have a 'DDAPI' solution. In these cases, you should just define them normally:
- - animations.lua
- - sapienObjectSnapping.lua
+
+- animations.lua
+- sapienObjectSnapping.lua

docs/hammerstone/ddapi/ddapi-troubleshooting.md

@@ -25,4 +25,4 @@ Objects in Sapiens need the "plans" to be added. Resources have their own plans.
 
 ### Object crashes when a Sapien picks it up
 
-Likely a storage issue.
+Likely a storage issue. Confirm that the object has a valid storage definition (defined in resource component)

docs/hammerstone/getting-started.md

@@ -10,7 +10,7 @@ You should download/clone Hammerstone to your mods directory, e.g. `%appdata%\ma
 
 Hammerstone is a framework. The next steps for you depend entirely on what you're trying to create. Here are some systems you might want to explore:
 
-- Get started with logging with [Logger](./utilities/logger.md).
+- Get started with the Data Driven Framework with [DDAPI](./ddapi/ddapi-getting-started.md).
 - Get started with UI with [UI Manager](./systems/ui-manager.md).
 - Get started with input with [Input Manager](./systems/input-manager.md)
 - Get started with game saves with [Save State Manager](./systems/save-state.md)

docs/hammerstone/introduction.md

@@ -1,17 +1,18 @@
 ![Hammerstone Logo](/images/hammerstone/hammerstone_wide.png)
 
-Hammerstone is a modding API and framework for the Sapiens video game. It aims to improve compatibility between mods and provide several useful features to mod developers. It has no functionality by itself.
+Hammerstone is a modding API and framework for Sapiens. It aims to improve compatibility between mods and provide several useful features to mod developers. It has no functionality by itself.
 
+Hammerstone has over 10,000 installs, so it's a "safe" dependency to include in your development journey. Anyone interested in using your mod will most likely have it installed already.
 
 ## Why use Hammerstone?
 
-Modding is a tricky topic, because it requires interacting with *game code* directly, often in uncomfortable, or unintuitive ways. The code cleanliness and design requirements for *writing a game* are often quite different from the aspects that make a game fun and easy to mod. 
+Modding is a tricky topic, because it requires interacting with _game code_ directly, often in uncomfortable, or unintuitive ways. The code cleanliness and design requirements for _writing a game_ are often quite different from the aspects that make a game fun and easy to mod.
 
-Enter, **Hammerstone**. A framework provides a layer of insulation between game code, and modder code. And since modders have full control over this layer, we can pack it full of as many utilities and helpers.
+Enter, **Hammerstone**. A framework provides a layer of insulation between game code, and modder code. And since modders have full control over this layer, we can pack it full of as many utilities and helpers as we want.
 
 ### Insulation from Game Code
 
-When Sapiens updates, some mods may break. This is an undeniable risk of building projects against an early access game. By piping your logic through **Hammerstone**, you gain a layer of protection from these breaking changes. While your mod *may break*, it may also be automatically fixed when Hammerstone is updated to support the latest version of Sapiens. When everyone is using the same API, we can focus our efforts on bringing back compatibility, without changing the external API.
+When Sapiens updates, some mods may break. This is an undeniable risk of building projects against an early access game. By piping your logic through **Hammerstone**, you gain a layer of protection from these breaking changes. While your mod _may break_, it may also be automatically fixed when Hammerstone is updated to support the latest version of Sapiens. When everyone is using the same API, we can focus our efforts on bringing back compatibility, without changing the external API.
 
 ### A real API
 
@@ -21,21 +22,22 @@ Hammerstone is packed full of things targeted at modders so it acts as a public
 
 ## What does Hammerstone offer?
 
-Hammerstone offers a *lot*, but it's generally broken into three sections:
+Hammerstone offers a _lot_, but it's generally broken into three sections:
 
 ### Simple Additions and Utilities
 
-Hammerstone is implemented as a collection of shadows on base game code. These shadows use priority **0**, which means that when you shadow these self-same files, you are receiving a module which is pre-configured by Hammerstone for your use. 
+Hammerstone is implemented as a collection of shadows on base game code. These shadows use priority **0**, which means that when you shadow these self-same files, you are receiving a module which is pre-configured by Hammerstone for your use.
 
-For example, `storage:addStorage`, which allows adding a storage, with logging and error checking. Without the `addStorage` method, you would need to inject the data yourself into the storage module, and re-configure the type-maps. Using Hammerstone allows you to benefit from these little utilities and functions, seamlessly integrated into the base game modules.
+For example, Hammerstone adds the function `storage:addStorage`, which allows adding a storage, with logging and error checking. Without the `addStorage` method, you would need to inject the data yourself into the storage module, and re-configure the type-maps. Using Hammerstone allows you to benefit from these little utilities and functions, seamlessly integrated into the base game modules.
 
 ### Systems
 
 Hammerstone offers a number of modules, external to any base game files, which you can require in your projects. These systems provide 'API' access to complex parts of the game code. In other words, rather than shadowing many files, in order to achieve a goal, you can rather require a Hammerstone system. Examples of systems include:
- - `inputManager` for input handling
- - `saveState` for writing and reading values into the save-game system (saved, for next play-through!)
- - `uiManager` for registering UI classes into various 'slots'
+
+- `inputManager` for input handling
+- `saveState` for writing and reading values into the save-game system (saved, for next play-through!)
+- `uiManager` for registering UI classes into various 'slots'
 
 ### Data Driven API
 
-Last but not least, Hammerstone offers a config-driven API for modding Sapiens. This ambitious effort transforms the data-flow in mods entirely, allowing you to define your mod as configuration files, rather than shadowing dozens of base game files. You can read more about the 'DDAPI' (data driven API) in its own section.
+Last but not least, Hammerstone offers a config-driven API for modding Sapiens. This ambitious effort transforms the data-flow in mods entirely, allowing you to define your mod as configuration files, rather than shadowing dozens of base game files. You can read more about the 'DDAPI' (data driven API) in its own section.