From d8e38abedcf5d5d7319c32eff0ab3270fb82dd72 Mon Sep 17 00:00:00 2001
From: SirLich <lrkoehler77@gmail.com>
Date: Sat, 28 Nov 2020 23:42:10 +0100
Subject: [PATCH] Update concepts doc

---
 concepts/render-controller.md | 63 +++++++++++++++++++++++------------
 1 file changed, 42 insertions(+), 21 deletions(-)

diff --git a/concepts/render-controller.md b/concepts/render-controller.md
index 27557c60..811365e0 100644
--- a/concepts/render-controller.md
+++ b/concepts/render-controller.md
@@ -18,22 +18,36 @@ parent: Concepts
 Beginner
 {: .label .label-green }
 
-Render controllers are an often-missunderstood part of the Resource Pack ecosystem. You should think of render-controllers as logic packs that take short-name definitions from the Resource Entity File (from now on, the entity file), and determine how they will be combined/layered/rendered in-game.
+Render controllers are an often-misunderstood part of the `Resource Pack`. But you don't need to be afraid! You should think of render-controllers as logic packs that take `short-name` definitions from the RP Entity File, and determine how they will be combined/layered/rendered in-game.
 
 # Defining short-names
 
-Render controllers work based on the short-name definitions of the entity file. For example, variables such as `geometry`, `materials`, and `textures` can be defined in the entity, and then accessed in the render controller. For example, like this:
+Render controllers work based on the short-name definitions of the RP entity file. Short-names are local identifiers, which we define in the RP entity file, and can then use in the render controller (and other places!). Variables such as `geometry`, `materials`, and `textures` can be defined in the entity,
 
+Lets look at a simplified version of the spider RP entity file:
+
+{% include filepath.html path="RP/entity/spider.json" %}
 ```json
-"materials": {
-    "default": "spider",
-    "invisible": "spider_invisible"
-},
-"textures": {
-    "default": "textures/entity/spider/cave_spider"
-},
-"geometry": {
-    "default": "geometry.spider.v1.8"
+{
+    "format_version": "1.8.0",
+    "minecraft:client_entity": {
+        "description": {
+            "identifier": "minecraft:cave_spider",
+            "materials": {
+                "default": "spider",
+                "invisible": "spider_invisible"
+            },
+            "textures": {
+                "default": "textures/entity/spider/cave_spider"
+            },
+            "geometry": {
+                "default": "geometry.spider.v1.8"
+            },
+            "render_controllers": [
+                "controller.render.spider"
+            ]
+        }
+    }
 }
 ```
 
@@ -45,22 +59,29 @@ In this case, four short-name definitions have been created:
 
 You can define multiple short-names in each array, such as in the `materials` example above.
 
-You should think of short-name definitions as `importing` the assets you want. At this state, you are bringing in textures, geometry, etc. In the render-controller stage, you won't import anything. You will simply use the assets you already imported to create the rendered entity.
+You should think of short-name definitions as `importing` the assets you want. At this state, you are defining the textures, geometry, and materials that you want to use in your entity. In the render-controller stage, you won't import anything. You will simply use the assets you already imported to create the rendered entity.
 
 # Simple render-controller
 
 A simple render controller looks like this:
 
+{% include filepath.html path="RP/render_controllers/cow.render.json" %}
 ```json
- {
-  "format_version": "1.8.0",
-  "render_controllers": {
-    "controller.render.cow": {
-      "geometry": "Geometry.default",
-      "materials": [ { "*": "Material.default" } ],
-      "textures": [ "Texture.default" ]
+{
+    "format_version": "1.8.0",
+    "render_controllers": {
+        "controller.render.cow": {
+            "geometry": "Geometry.default",
+            "materials": [
+                {
+                    "*": "Material.default"
+                }
+            ],
+            "textures": [
+                "Texture.default"
+            ]
+        }
     }
-  }
 }
 ```
 
@@ -72,7 +93,7 @@ Since render controllers work based on short-names, it is possible to re-use the
 
 For example, the render controller above is used for the `minecraft:cow` entity. If you want to use this render controller in your own pack, simple define like: `"render_controllers": [ "controller.render.cow" ]` in your entity file.
 
-`warning:` Remember! Render controllers work based on short-named. If you want to use the cow render controller, you need to provide the short-names it is using. In this case, you will need to provide:
+`warning:` Remember! Render controllers work based on short-names. If you want to use the cow render controller, you need to provide the short-names it is using. In this case, you will need to provide:
  - `default` geometry
  - `default` texture
  - `default` material