From 2f5bd4c3158888a83424abec730548223a02b81a Mon Sep 17 00:00:00 2001
From: lambdalemon <lemonjameslem@protonmail.com>
Date: Fri, 15 Aug 2025 23:16:01 -0400
Subject: [PATCH] Loads of docs some wip

---
 .gitignore                                    |   1 +
 src/SUMMARY.md                                |  12 +-
 src/contributor-guide.md                      |  48 ++++
 src/internal_apis/README.md                   |   3 +
 .../pypostprocessing/data_stage.md            |   8 +
 src/internal_apis/pypostprocessing/entity.md  |  46 ++++
 src/internal_apis/pypostprocessing/fluid.md   |  12 +
 src/internal_apis/pypostprocessing/item.md    |  54 +++++
 src/internal_apis/pypostprocessing/recipe.md  | 223 ++++++++++++++++++
 .../pypostprocessing/technology.md            |   9 +
 .../pypostprocessing/template.md              |   7 +
 src/internal_apis/pypostprocessing/tile.md    |   8 +
 src/special_apis/README.md                    |   5 +
 src/special_apis/digosaurs.md                 |  14 ++
 14 files changed, 449 insertions(+), 1 deletion(-)
 create mode 100644 .gitignore
 create mode 100644 src/contributor-guide.md
 create mode 100644 src/internal_apis/README.md
 create mode 100644 src/internal_apis/pypostprocessing/data_stage.md
 create mode 100644 src/internal_apis/pypostprocessing/entity.md
 create mode 100644 src/internal_apis/pypostprocessing/fluid.md
 create mode 100644 src/internal_apis/pypostprocessing/item.md
 create mode 100644 src/internal_apis/pypostprocessing/recipe.md
 create mode 100644 src/internal_apis/pypostprocessing/technology.md
 create mode 100644 src/internal_apis/pypostprocessing/template.md
 create mode 100644 src/internal_apis/pypostprocessing/tile.md
 create mode 100644 src/special_apis/README.md
 create mode 100644 src/special_apis/digosaurs.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..3006b27
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+book/
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 7390c82..bf36af5 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -1,3 +1,13 @@
 # Summary
 
-- [Chapter 1](./chapter_1.md)
+- [Contributor Guide](./contributor-guide.md)
+- [Internal APIs](./internal_apis/README.md)
+  - [PyPostProcessing Data Stage](./internal_apis/pypostprocessing/data_stage.md)
+    - [Item](./internal_apis/pypostprocessing/item.md)
+    - [Entity](./internal_apis/pypostprocessing/entity.md)
+    - [Fluid](./internal_apis/pypostprocessing/fluid.md)
+    - [Recipe](./internal_apis/pypostprocessing/recipe.md)
+    - [Technology](./internal_apis/pypostprocessing/technology.md)
+    - [Tile](./internal_apis/pypostprocessing/tile.md)
+- [Special APIs](./special_apis/README.md)
+  - [Digosaurs](./special_apis/digosaurs.md)
diff --git a/src/contributor-guide.md b/src/contributor-guide.md
new file mode 100644
index 0000000..72eaa2f
--- /dev/null
+++ b/src/contributor-guide.md
@@ -0,0 +1,48 @@
+# Contributor Guide
+
+### How to commit
+
+List of good resources to find out what to do:
+  - [Good first Issues](https://github.com/pyanodon/pybugreports/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
+  - [Py Roadmap](https://github.com/orgs/pyanodon/projects/2/views/4)
+
+How can I contribute?
+  1. Clone the repo you want to commit to
+  2. Create a new branch off of main
+  3. Create the changes you want to add
+  4. Create a pull request describing what you fixed or what you're adding, for simple bug reports you can just say “Fixes <issue link>”
+  5. Wait for approval
+  6. Make changes if needed
+  7. Boom dopamine
+
+### General Layout
+
+We have 2 branches for different updates: Master or Main and Breaking Changes
+- Main or Master is used for bug fixes, general fixes, or non-removing enhancements.
+- Breaking changes is used for breaking changes like changing the output of a recipe to have a new byproduct.
+
+The codebase will look something like this typically
+```
+pytesting
+├── control.lua
+├── data.lua
+├── scripts
+│      └── example.lua
+└── prototypes
+         ├── buildings
+         │      └── example-building.lua
+         ├── items
+         │      └── items.lua
+         ├── recipes
+         │      └── recipes.lua
+         └── technologies
+                  └── exmple-technology.lua
+```
+
+### Frequently Asked Questions
+
+Where are pypostprocessing functions located at?
+
+`pypostprocessing/lib` for in-general stuff<br>
+`pypostprocessing/lib/metas` for prototyping functions<br>
+`pypostprocessing/lib/events` for control event functions
diff --git a/src/internal_apis/README.md b/src/internal_apis/README.md
new file mode 100644
index 0000000..cc0eb66
--- /dev/null
+++ b/src/internal_apis/README.md
@@ -0,0 +1,3 @@
+# Internal APIs
+
+Internal APIs are things like `pypostprocessing` functions.
diff --git a/src/internal_apis/pypostprocessing/data_stage.md b/src/internal_apis/pypostprocessing/data_stage.md
new file mode 100644
index 0000000..302aadd
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/data_stage.md
@@ -0,0 +1,8 @@
+# PyPostProcessing Data Stage
+
+- [Item](./item.md) Information about the `ITEM` function.
+- [Entity](./entity.md) Information about the `ENTITY` function.
+- [Fluid](./fluid.md) Information about the `FLUID` function.
+- [Recipe](./recipe.md) Information about the `RECIPE` function.
+- [Technology](./technology.md) Information about the `TECHNOLOGY` function.
+- [Tile](./tile.md) Information about the `TILE` function.
diff --git a/src/internal_apis/pypostprocessing/entity.md b/src/internal_apis/pypostprocessing/entity.md
new file mode 100644
index 0000000..45d3c1e
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/entity.md
@@ -0,0 +1,46 @@
+# Entity
+```lua
+---@class data.EntityPrototype
+---@field public standardize fun(self: data.EntityPrototype): data.EntityPrototype
+---@field public add_flag fun(self: data.EntityPrototype, flag: string): data.EntityPrototype
+---@field public remove_flag fun(self: data.EntityPrototype, flag: string): data.EntityPrototype
+---@field public has_flag fun(self: data.EntityPrototype, flag: string): boolean
+```
+
+## Example Usage
+`ENTITY` function can be used like this to create a new entity:
+```lua
+ENTITY {
+  type = "assembling-machine",
+  name = "example-entity",
+  icon = "__pyexample__/graphics/icons/example.png",
+  icon_size = 64,
+  ...
+}
+```
+It can also be used to get an existing entity:
+```lua
+ENTITY("example-entity")
+```
+
+## Entity Functions
+### Add Flag
+`@field public add_flag fun(self: data.EntityPrototype, flag: string): data.EntityPrototype`
+```lua
+local flag = "placeable-by-player"
+ENTITY("example-item"):add_flag(flag)
+```
+
+### Remove Flag
+`@field public remove_flag fun(self: data.EntityPrototype, flag: string): data.EntityPrototype`
+```lua
+local flag = "placeable-by-player"
+ENTITY("example-item"):remove_flag(flag)
+```
+
+### Has Flag
+`@field public has_flag fun(self: data.EntityPrototype, flag: string): boolean`
+```lua
+local flag = "placeable-by-player"
+local has_flag = ENTITY("example-item"):has_flag(flag)
+```
diff --git a/src/internal_apis/pypostprocessing/fluid.md b/src/internal_apis/pypostprocessing/fluid.md
new file mode 100644
index 0000000..4c737c2
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/fluid.md
@@ -0,0 +1,12 @@
+# Fluid
+`FLUID` can be used like so:
+```lua
+FLUID{
+  type = "fluid",
+  name = "example-fluid"
+}
+```
+You can also use it to get existing fluids
+```lua
+FLUID("example-fluid")
+```
diff --git a/src/internal_apis/pypostprocessing/item.md b/src/internal_apis/pypostprocessing/item.md
new file mode 100644
index 0000000..8415bad
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/item.md
@@ -0,0 +1,54 @@
+# Items
+```lua
+---@class data.ItemPrototype
+---@field public add_flag fun(self: data.ItemPrototype, flag: string): data.ItemPrototype
+---@field public remove_flag fun(self: data.ItemPrototype, flag: string): data.ItemPrototype
+---@field public has_flag fun(self: data.ItemPrototype, flag: string): boolean
+---@field public spoil fun(self: data.ItemPrototype, spoil_result: (string | table), spoil_ticks: number): data.ItemPrototype
+```
+
+## Example Usage
+`ITEM` function can be used like this to create a new item:
+```lua
+ITEM {
+  type = "item",
+  name = "example-item",
+  icon = "__pyexample__/graphics/icons/example.png",
+  icon_size = 64,
+  stack_size = 50
+}
+```
+It can also be used like this to get an existing item:
+```lua
+ITEM("example-item")
+```
+
+## Item Functions
+### Spoil
+`@field public spoil fun(self: data.ItemPrototype, spoil_result: (string | table), spoil_ticks: number): data.ItemPrototype`
+```lua
+local spoil_result = "iron-plate"
+local spoil_ticks = 5 * 60 -- 5 Seconds
+ITEM("example-item"):spoil(spoil_result, spoil_ticks)
+```
+
+### Add Flag
+`@field public add_flag fun(self: data.ItemPrototype, flag: string): data.ItemPrototype`
+```lua
+local flag = "placeable-by-player"
+ITEM("example-item"):add_flag(flag)
+```
+
+### Remove Flag
+`@field public remove_flag fun(self: data.ItemPrototype, flag: string): data.ItemPrototype`
+```lua
+local flag = "placeable-by-player"
+ITEM("example-item"):remove_flag(flag)
+```
+
+### Has Flag
+`@field public has_flag fun(self: data.ItemPrototype, flag: string): boolean`
+```lua
+local flag = "placeable-by-player"
+local has_flag = ITEM("example-item"):has_flag(flag)
+```
diff --git a/src/internal_apis/pypostprocessing/recipe.md b/src/internal_apis/pypostprocessing/recipe.md
new file mode 100644
index 0000000..1e93e01
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/recipe.md
@@ -0,0 +1,223 @@
+# Recipe
+```lua
+---@class data.RecipePrototype
+---@field public standardize fun(self: data.RecipePrototype): data.RecipePrototype
+---@field public add_unlock fun(self: data.RecipePrototype, technology_name: string | string[]): data.RecipePrototype
+---@field public remove_unlock fun(self: data.RecipePrototype, technology_name: string | string[]): data.RecipePrototype
+---@field public replace_unlock fun(self: data.RecipePrototype, technology_old: string | string[], technology_new: string | string[]): data.RecipePrototype
+---@field public replace_ingredient fun(self: data.RecipePrototype, old_ingredient: string, new_ingredient: string | data.IngredientPrototype, new_amount: integer?): data.RecipePrototype
+---@field public add_ingredient fun(self: data.RecipePrototype, ingredient: data.IngredientPrototype): data.RecipePrototype
+---@field public remove_ingredient fun(self: data.RecipePrototype, ingredient_name: string): data.RecipePrototype, integer
+---@field public replace_result fun(self: data.RecipePrototype, old_result: string, new_result: string | data.ProductPrototype, new_amount: integer?): data.RecipePrototype
+---@field public add_result fun(self: data.RecipePrototype, result: string | data.ProductPrototype): data.RecipePrototype
+---@field public remove_result fun(self: data.RecipePrototype, result_name: string): data.RecipePrototype
+---@field public clear_ingredients fun(self: data.RecipePrototype): data.RecipePrototype
+---@field public multiply_result_amount fun(self: data.RecipePrototype, result_name: string, percent: number): data.RecipePrototype
+---@field public multiply_ingredient_amount fun(self: data.RecipePrototype, ingredient_name: string, percent: number): data.RecipePrototype
+---@field public add_result_amount fun(self: data.RecipePrototype, result_name: string, increase: number): data.RecipePrototype
+---@field public add_ingredient_amount fun(self: data.RecipePrototype, ingredient_name: string, increase: number): data.RecipePrototype
+---@field public set_result_amount fun(self: data.RecipePrototype, result_name: string, amount: number): data.RecipePrototype
+---@field public set_ingredient_amount fun(self: data.RecipePrototype, ingredient_name: string, amount: number): data.RecipePrototype
+---@field public get_main_product fun(self: data.RecipePrototype, allow_multi_product: bool?): LuaItemPrototype?|LuaFluidPrototype?
+---@field public get_icons fun(self: data.RecipePrototype): data.IconData
+```
+
+## Example Usage
+You can create a new recipe like so:
+```lua
+RECIPE {
+  type = "recipe",
+  name = "example-recipe",
+  ingredients = {},
+  results = {{type = "item", name = "example-item", amount = 1}}
+}
+```
+You can also get existing recipes
+```lua
+RECIPE("example-recipe")
+```
+
+## Recipe Functions
+### Add Unlock
+`@field public add_unlock fun(self: data.RecipePrototype, technology_name: string | string[]): data.RecipePrototype`
+```lua
+local technology_name = "example-tech"
+RECIPE("example-recipe"):add_unlock(technology_name)
+```
+```lua
+local technologies = {"example-tech", "example-tech-2"}
+RECIPE("example-recipe"):add_unlock{technologies}
+```
+
+### Remove Unlock
+`@field public remove_unlock fun(self: data.RecipePrototype, technology_name: string | string[]): data.RecipePrototype`
+```lua
+local technology_name = "example-tech"
+RECIPE("example-recipe"):remove_unlock(technology_name)
+```
+```lua
+local technologies = {"example-tech", "example-tech-2"}
+RECIPE("example-recipe"):remove_unlock{technologies}
+```
+
+### Replace Unlock
+`@field public replace_unlock fun(self: data.RecipePrototype, technology_old: string | string[], technology_new: string | string[]): data.RecipePrototype`
+
+Equivalent to `:remove_unlock(from):add_unlock(to)`
+```lua
+local from = "example-tech"
+local to = "ultra-tech"
+RECIPE("example-recipe"):replace_unlock(from, to)
+```
+```lua
+local from = {"example-tech", "example-tech-2"}
+local to = {"ultra-tech", "ultra-tech-2"} 
+RECIPE("example-recipe"):replace_unlock(from, to)
+```
+
+### Add Ingredient
+`@field public add_ingredient fun(self: data.RecipePrototype, ingredient: data.IngredientPrototype): data.RecipePrototype`
+```lua
+RECIPE("example-recipe"):add_ingredient{
+  type = "item",
+  name = "iron-plate",
+  amount = 5
+}
+```
+
+### Remove Ingredient
+`@field public remove_ingredient fun(self: data.RecipePrototype, ingredient_name: string): data.RecipePrototype, integer`
+```lua
+RECIPE("example-recipe"):remove_ingredient("iron-plate")
+```
+
+### Replace Ingredient
+`@field public replace_ingredient fun(self: data.RecipePrototype, old_ingredient: string, new_ingredient: string | data.IngredientPrototype, new_amount: integer?): data.RecipePrototype`
+```lua
+local from = "iron-plate"
+local to = "copper-plate"
+RECIPE("example-recipe"):replace_ingredient(from, to)
+```
+```lua
+local from = "iron-plate"
+local to = {
+  type = "item",
+  name = "copper-plate",
+  amount = 5
+}
+RECIPE("example-recipe"):replace_ingredient(from, to)
+```
+```lua
+local from = "iron-plate"
+local to = "copper-plate"
+local amount = 10
+RECIPE("example-recipe"):replace_ingredient(from, to, amount)
+```
+
+### Clear Ingredients
+`@field public clear_ingredients fun(self: data.RecipePrototype): data.RecipePrototype`
+```lua
+RECIPE("example-recipe"):clear_ingredients()
+```
+
+### Add Result
+`@field public add_result fun(self: data.RecipePrototype, result: string | data.ProductPrototype): data.RecipePrototype`
+```lua
+RECIPE("example-recipe"):add_result{
+  type = "item",
+  name = "iron-plate",
+  amount = 5
+}
+```
+
+### Remove Result
+`@field public remove_result fun(self: data.RecipePrototype, result_name: string): data.RecipePrototype`
+```lua
+RECIPE("example-recipe"):remove_result("iron-plate")
+```
+
+### Replace Result
+`@field public replace_result fun(self: data.RecipePrototype, old_result: string, new_result: string | data.ProductPrototype, new_amount: integer?): data.RecipePrototype`
+```lua
+local from = "iron-plate"
+local to = "copper-plate"
+RECIPE("example-recipe"):replace_result(from, to)
+```
+```lua
+local from = "iron-plate"
+local to = {
+  type = "item",
+  name = "copper-plate",
+  amount = 5
+}
+RECIPE("example-recipe"):replace_result(from, to)
+```
+```lua
+local from = "iron-plate"
+local to = "copper-plate"
+local amount = 10
+RECIPE("example-recipe"):replace_result(from, to, amount)
+```
+
+### Multiply Result Amount
+`@field public multiply_result_amount fun(self: data.RecipePrototype, result_name: string, percent: number): data.RecipePrototype`
+```lua
+local name = "iron-plate"
+local percent = 1.5
+RECIPE("example-recipe"):multiply_result_amount(name, percent)
+```
+
+### Multiply Ingredient Amount
+`@field public multiply_ingredient_amount fun(self: data.RecipePrototype, ingredient_name: string, percent: number): data.RecipePrototype`
+```lua
+local name = "iron-plate"
+local percent = 1.5
+RECIPE("example-recipe"):multiply_ingredient_amount(name, percent)
+```
+
+### Add Result Amount
+`@field public add_result_amount fun(self: data.RecipePrototype, result_name: string, increase: number): data.RecipePrototype`
+```lua
+local name = "iron-plate"
+local increase = 10
+RECIPE("example-recipe"):add_result_amount(name, increase)
+```
+
+### Add Ingredient Amount
+`@field public add_ingredient_amount fun(self: data.RecipePrototype, ingredient_name: string, increase: number): data.RecipePrototype`
+```lua
+local name = "iron-plate"
+local increase = 10
+RECIPE("example-recipe"):add_ingredient_amount(name, increase)
+```
+
+### Set Result Amount
+`@field public set_result_amount fun(self: data.RecipePrototype, result_name: string, amount: number): data.RecipePrototype`
+```lua
+local name = "iron-plate"
+local amount = 10
+RECIPE("example-recipe"):set_result_amount(name, amount)
+```
+
+### Set Ingredient Amount
+`@field public set_ingredient_amount fun(self: data.RecipePrototype, ingredient_name: string, amount: number): data.RecipePrototype`
+```lua
+local name = "iron-plate"
+local amount = 10
+RECIPE("example-recipe"):set_ingredient_amount(name, amount)
+```
+
+### Get Main Product
+`@field public get_main_product fun(self: data.RecipePrototype, allow_multi_product: bool?): LuaItemPrototype?|LuaFluidPrototype?`
+```lua
+local main_product = RECIPE("example-recipe"):get_main_product()
+```
+```lua
+local main_products = RECIPE("example-recipe"):get_main_product(true)
+```
+
+### Get Icons
+`@field public get_icons fun(self: data.RecipePrototype): data.IconData`
+```lua
+local icons = RECIPE("example-recipe"):get_icons()
+```
diff --git a/src/internal_apis/pypostprocessing/technology.md b/src/internal_apis/pypostprocessing/technology.md
new file mode 100644
index 0000000..14e0eae
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/technology.md
@@ -0,0 +1,9 @@
+# Technology
+# WIP
+
+```lua
+```
+
+## Example Usage
+
+## Technology Functions
diff --git a/src/internal_apis/pypostprocessing/template.md b/src/internal_apis/pypostprocessing/template.md
new file mode 100644
index 0000000..45289e2
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/template.md
@@ -0,0 +1,7 @@
+# PLACEHOLDER
+```lua
+```
+
+## Example Usage
+
+## PLACEHOLDER Functions
diff --git a/src/internal_apis/pypostprocessing/tile.md b/src/internal_apis/pypostprocessing/tile.md
new file mode 100644
index 0000000..642464a
--- /dev/null
+++ b/src/internal_apis/pypostprocessing/tile.md
@@ -0,0 +1,8 @@
+# Tile
+# WIP
+```lua
+```
+
+## Example Usage
+
+## Tile Functions
diff --git a/src/special_apis/README.md b/src/special_apis/README.md
new file mode 100644
index 0000000..0436ae9
--- /dev/null
+++ b/src/special_apis/README.md
@@ -0,0 +1,5 @@
+# Special APIs
+
+What are Special APIs? Special APIs are remote interfaces or internal parts of the pYmod ecosystem that do a certain specialized thing.
+
+An example is: Remote interfaces for adding new digosaurs.
diff --git a/src/special_apis/digosaurs.md b/src/special_apis/digosaurs.md
new file mode 100644
index 0000000..420bb76
--- /dev/null
+++ b/src/special_apis/digosaurs.md
@@ -0,0 +1,14 @@
+# Digosaurs
+
+You can add a new digosaur like this:
+```lua
+local name = "my-new-digosaur"
+local bonus = 2
+local proxy_name = "my-nex-digosaur-proxy"
+remote.call("py_digosaurs", "new_digosaur", name, bonus, proxy_name)
+```
+
+You can also remove existing digosaurs like so:
+```lua
+remote.call("py_digosaurs", "remove_digosaur", "digosaurus")
+```