diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ecebee..fa588de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,9 @@ Versions before 2.1.2 have been backfilled; I gotta be more on top of changelogs
* Remove some unused stuff from the jar
* Code cleanups, hopefully without breaking ABI compat (i don't have an ABI checker in the pipeline tho)
+* Fix a bug where templates that look like blocks with randomized models, such as stone, could reroll their blockstate on every resource load.
+ * Forgot to specify a random seed.
+ * All templated blocks still use the *same* model, so templated stone will still not be randomly rotated/flipped, but at least it's now the *same* same model.
road map:
diff --git a/README.md b/README.md
index e6daa6b..f5e8fff 100644
--- a/README.md
+++ b/README.md
@@ -8,72 +8,127 @@
**This mod is open source and under a permissive license.** As such, it can be included in any modpack on any platform without prior permission. We appreciate hearing about people using our mods, but you do not need to ask to use them. See the [LICENSE file](LICENSE) for more details.
-Template blocks can be placed in the world, then right-clicked with a full-size block to set the textures for the template. Template blocks will inherit light and redstone values from the blocks they're given, or they can have light or redstone output added to any given block by right-clicking the template with glowstone dust or a redstone torch, respectively.
+If a Template block is placed in the world and right-clicked with a full-size block, it will take on the appearance of that block. Template blocks will inherit light and redstone values from the blocks they're given. Adding a *redstone torch* will make them emit redstone power, *glowstone dust* will make them emit light, and *popped chorus fruit* will make them intangible.
-While Templates itself adds a handful of common shapes, it's also not too hard for other mods to interface with Templates and add their own templatable blocks.
-
-# quat was here
-
-Todo move this into the main readme section
-
-COOL RIVULET is by mev , this is the most important block in the mod & perhaps the most important block in any mod ever since `incorporeal:clearly`
-
-## Todo
-
-* More templates !!
+While Templates itself adds a handful of common shapes, it's not too hard for other mods to interface with Templates and add their own templatable blocks.
# For addon developers
+## Creating a block entity
+
+All templates need a block entity to store what block they look like. Templates registers one under `templates:slope`[^1], but as an addon developer you can't add additional blocks to my block entity. (Don't try, please.)
+
+To that end, nothing in Templates relies on the *specific* block entity ID, so just re-register `TemplateEntity` under your own name. You are free to extend `TemplateEntity` as well.
+
+The only hard requirement on the block entity is that it `implements ThemeableBlockEntity`. (This implies it returns a `BlockEntity` from `getRenderAttachmentData`.)
+
## Creating your block
-So there are various block interactions in Templates, like adding glowstone to make the block illuminate, adding redstone to make it a power source, etc.
+There are various block interactions in Templates, like adding redstone to make the block emit power. To make your block fit with the other Templates, you'll want those behaviors to apply to your block as well. There's a couple options, depending on the complexity of the block you'd like to "template-ify".
-In an ideal world, I'd be able to simply provide the `TemplateBlock` class implementing all those features and ask that you extend it from your block. If your block doesn't already have a superclass I recommend doing this - alas, if it does, you can't also extend `TemplateBlock`, so the implementation of everything has been farmed out to `public static` methods in `TemplateInteractionUtil` in the api package. Simply wire everything up.
+If you simply registered a `Block` or a simple vanilla class like `WallBlock`, use the corresponding class in `io.github.cottonmc.templates.block`.
-Don't forget to feed your `Block.Settings` through `TemplateInteractionUtil.configureSettings` too, and if there's any behaviors you'd like to tweak, try implementing some methods from `TemplateInteractionUtilExt` before resorting to copy-pasting the implementation of `TemplateInteractionUtil` methods. But copy paste away if you must.
+If you registered something different (like a `MyFancyBlock`), the simplest approach is to leverage `TemplateInteractionUtil`, which is where all of the interaction code lives in a mildly "pluggable" form. Here are the suggested steps:
-The only other requirement is that your block *must* have a block entity, that both returns a `BlockState` object from `RenderAttachmentBlockEntity.getRenderAttachmentData` and implements `ThemeableBlockEntity`. `TemplateEntity` is an implementation of this (and also implements the other half of the features from `TemplateInteractionUtil`); I recommend using it if you can.
+* Create a `TemplateMyFancyBlock` class that extends your block class.
+* Copy-paste the body of `TemplateBlock` into it; adjust the constructor as needed. (It was designed to be copy-pasted in this way; this is how i filled out most of the other classes.)
+* Make sure it instantiates your block entity type.
+* Check that the methods are implemented the way you'd like.
+ * Particularly you might want to look at the redstone emission methods; the default ones don't call `super`.
+
+And if all else fails, just reimplement whatever interactions you'd like, or simply don't bother. None of this is important for the actual *retexturing* part of the mod, apart from returning a suitable block entity.
## Creating the custom model
(TL;DR look at `assets/templates/blockstates` and the bottom of `TemplatesClient`)
-To make a model retexturable, Templates has to know which faces you want to retexture, and which side of the block they correspond to. There are currently three ways to tell Templates your intentions:
+Of course Templates leverages custom baked models. All of Templates's baked model implementations find and retexture quads from an upstream source that you will need to provide.
+
+Templates needs three pieces of information to perform retexturing:
+
+* the quad to be retextured
+* whether you actually want to retexture it or just pass it through unchanged (see the Lever Template, which doesn't change the lever arm);
+* what face of the block it corresponds to (which is sometimes different from "the direction it points" - see the Door Template, the textures "stick" when you open the door)
+
+The last piece of information is important because Templates tries hard to retain the orientation of blocks placed inside of them - you can place specifically an *east-facing* log into a Template, for example, and some faces get the cut wood while other faces get the bark. (Some other mods just use the same texture on all faces of the block, like the particle texture.)
+
+Pick a model implementation that suits your needs:
### `UnbakedAutoRetexturedModel`
-Pass the ID of a JSON model to retexture. All quads that face east will be textured with the east side of the theme, all quads that face up will be textured with the top side of the theme, etc. There is no way to skip a face.
+* the quad: Sourced from a JSON model.
+* whether you want to retexture it: "Yes". All quads will be retextured.
+* what face of the block: Automatically determined by facing direction.
-Most of Templates's blocks use this model.
+To construct, pass the ID of the JSON model you want to source quads from.
+
+There's no way to configure this, so if you want to skip retexturing a face, try the next model implementation instead.
**TODO**: this does not work well with `multipart` models with differently-rotated parts, like the fence model (consisting of 1 fence post and 1 fence-side model that gets rotated around to fill all 4 sides)
### `UnbakedJsonRetexturedModel`
-Pass the ID of a JSON model to retexture. All quads textured with `templates:templates_special/east` will be textured with the east side of the theme, all quads textured with `templates:templates_special/up` will be retextured with the top side of the theme, etc. Quads textured with any other texture will be passed through unaltered.
+* the quad: Sourced from a JSON model.
+* whether you want to retexture it: Determined from the texture applied to the quad.
+* what face of the block: Determined via the texture applied to the quad.
-Templates's lever uses this model - `AutoRetexturedModel` was not appropriate because I did not want to retexture the lever arm.
+To construct, pass the ID of a JSON model to retexture. All quads textured with `templates:templates_special/east` will be textured with the east side of the theme, all quads textured with `templates:templates_special/up` will be retextured with the top side of the theme, etc. Quads textured with any other texture will be passed through unaltered.
-(This works better with multipart models.)
+Regarding texture variables:
+
+On the off-chance your blockmodel already has texture variables for `north`, `south`, etc, you can simply apply Templates's special textures to it:
+
+```json
+{
+ "parent": "mymod:block/my_model",
+ "textures": {
+ "north": "templates:templates_special/north",
+ "east": "templates:templates_special/east",
+ "south": "templates:templates_special/south",
+ "west": "templates:templates_special/west",
+ "up": "templates:templates_special/up",
+ "down": "templates:templates_special/down",
+ }
+}
+```
+
+Sadly, many models don't specify *completely* separate textures for all six sides. If you have a setup like an "ends" variable which gets applied to "the top and bottom" or something, please don't use the texture-variables approach. Instead, see if the `UnbakedAutoRetexturedModel` suits your needs, or make a second copy of the json model that does separately fill in all faces.
+