Regression-Games · abeizer · Jun 13, 2023 · Jun 7, 2023 · Jun 7, 2023 · Jun 8, 2023
diff --git a/docs/players/creating-bots/agent-builder.md b/docs/players/creating-bots/agent-builder.md
@@ -3,4 +3,128 @@ sidebar_label: 'Using the Agent-Builder'
 ---
 
 
-# Creating Bots Using the Agent-Builder
+# Creating AIs Using the Agent-Builder
+
+Regression Games' Agent-Builder is an easy-to-use visual editor for constructing AI behavior trees.
+Our editor utilizes large language models like [OpenAI's GPT-4](https://openai.com/blog/chatgpt) to write code for you.
+This makes our Agent-Builder an excellent tool for those new to our AI libraries, or even to programming itself!
+
+*Please note that this tool is early in development and is likely to contain bugs.*
+*You can report bugs and request additional features for the Agent-Builder [here](https://regression-games.sleekplan.app/feedback).*
+
+## What Is a Behavior Tree?
+
+A behavior tree is a decision-making model used to determine which actions an agent (such as a character in a video game) should take in different situations.
+You can think of it as a flow chart that the AI thinks through, choosing appropriate actions based on what it knows about itself and its environment.
+Behavior trees are composed of nodes organized in a hierarchical structure that start at a root node and branch out to form different paths.
+Each path represents a line of decision-making that results in one or more actions for the AI to take.
+
+Each node in the tree executes logic and returns one of the following states as a result:
+
+- **Running** -> The node is currently being executed and hasn't completed yet.
+- **Success** -> The node has completed successfully.
+- **Failure** -> The node has failed. This doesn't necessarily mean an error occurred. For example, a heal action might fail if the character doesn't have any potions.
+
+Different types of nodes have different responsibilities and react differently to the states of other nodes.
+
+- **Root Node**: The beginning of the tree, where the AI starts its decision-making.
+Its job is simply to execute whatever node is below it in the tree and return its state.
+- **Sequence Node**: This node has one or more children and acts as a logical AND.
+It executes its child nodes one at a time, and if any of them fail then the Sequence Node immediately fails.
+- **Selector Node**: This node also has one or more children, but acts as an OR.
+It executes each of its children and if one of them succeeds, then the Selector Node immediately succeeds.
+- **Action Node**: This node is a leaf node, meaning it cannot have any children of its own.
+Instead, it represents an action for the AI to take such as moving in a certain direction or interacting with an object in its environment.
+- **Condition Node**: This node is also a leaf node. It evaluates whether certain conditions have been satisfied.
+- **Decorator Node**: There are several kinds of Decorator Nodes, each of which can have only one child. This node modifies its child's state in some way.
+For example, an "Inverter" Decorator will succeed if its child fails, and vice versa.
+
+For a deeper dive into behavior trees, their different nodes, and practical examples of using them in video games, [follow this link](https://www.gamedeveloper.com/programming/behavior-trees-for-ai-how-they-work).
+
+## Getting Started with Agent-Builder
+
+Create a new AI from the Bot Manager and select Agent-Builder from the list of creation options
+(see this section's [overview](./overview.md) for a walkthrough of AI creation).
+
+![Create new AI](./img/create-bot-button.png)
+![Use Agent-Builder](./img/agent-builder/create-with-agent-builder.png)
+
+### Creating Nodes
+
+Once you've created your AI, you'll be redirected to the Agent-Builder interface.
+We'll start you out with a root node and a sequence node to form the basis of your tree.
+
+![Default Tree](./img/agent-builder/default-tree.png)
+
+To start building your tree, click the connector at the bottom of the sequence node and drag.
+When you release, you'll be presented with different types of nodes that can be added to the sequence.
+For this demonstration, we'll create an action node.
+You can repeat this process for any node that is allowed to have children.
+
+![Select a Node Type](./img/agent-builder/select-node-type.png)
+![Create an Action Node](./img/agent-builder/new-action-node.png)
+![Example Tree](./img/agent-builder/example-tree-1.png)
+
+Clicking on a node opens a panel to the right side of your screen.
+This panel contains information about the selected node including a description of the node's type and a label, as well as a button to delete the node from the tree.
+It's a good idea to set labels to keep track of what you want each node or branch to do.
+If the selected node is a leaf node, such as an action or condition, the panel will also contain fields used for code generation.
+
+![Open the Node Panel](./img/agent-builder/edit-node.png)
+
+### Generating Code
+
+The nodes in your tree won't be useful until you give them some logic to execute.
+Click on a leaf node to open the side-panel and describe what you want this node to do in the "GPT Prompt" field.
+When you're satisfied with your prompt, click the "Generate Code" button to watch code appear in the editor.
+
+We provide additional context to GPT so that it can use our APIs but it may produce output that doesn't follow our expected format,
+or code that functions differently in-game than your prompt intends.
+If this happens, you can make changes to your prompt and re-submit it for new output, or you can manually edit the output yourself in the editor.
+
+#### Typescript
+
+Agent-Builder currently only supports Typescript. If you'd like to see support for other languages, let us know [here](https://regression-games.sleekplan.app/feedback).
+
+The below sample uses the [rg-bot library for Minecraft](TODO-REG-1026) to make the AI wander in a random direction.
+This is a good example of well-formatted output.
+The output must only contain valid code and must implement a method with the signature `public override async execute(): Promise<NodeStatus>` which acts as our entrypoint into the node.
+The `getData` and `setData` methods can be used to easily share data between nodes.
+
+![Generate Code](./img/agent-builder/generate-code.png)
+
+### Saving Your Tree
+
+Save your tree early and often! Any changes made to your AI will be lost if you leave the Agent-Builder without saving.
+
+![Save Your Tree](./img/agent-builder/save-tree.png)
+
+## Editing an AI using Agent-Builder
+
+If you've used the Agent-Builder to create an AI before, you can locate that AI in the Bot Manager and open the Agent-Builder interface.
+Once the interface is visible, tell Regression Games to load your tree from GitHub. You should now see your tree and be able to edit its nodes.
+Don't forget to save when you're done!
+
+![Open Agent Builder](./img/agent-builder/open-agent-builder.png)
+![Load Your Tree](./img/agent-builder/load-tree.png)
+
+## Editing an AI's source code
+
+Whenever you save your tree, multiple files are pushed to GitHub - a config file named `agentBuilderWorkspace.json` which defines the nodes in your tree,
+and a series of typescript files generated from the config that are used to run your AI in-game.
+
+```
+├── lib
+│   ├── BaseClasses
+│   │   ├── **/*.ts
+│   ├── **/*.ts
+├── agentBuilderWorkspace.json
+├── index.ts
+├── package.json
+├── tsconfig.json
+└── .gitignore
+```
+
+You can modify these files in your favorite IDE for more control over the AI's behaviors and dependencies.
+However, changes made to files other than the `agentBuilderWorkspace.json` **will be overwritten if you save this tree again from the Agent-Builder interface.**
+See the [Writing Your Own Code section](TODO-REG-1023) for more information.
diff --git a/docs/players/creating-bots/coding/updating-your-ai.md b/docs/players/creating-bots/coding/updating-your-ai.md
@@ -0,0 +1,5 @@
+---
+sidebar_label: 'Updating Your AI'
+---
+
+# Updating Your AI
diff --git a/docs/players/creating-bots/coding/upload-zip.md b/docs/players/creating-bots/coding/upload-zip.md
@@ -0,0 +1,3 @@
+---
+sidebar_label: 'Uploading a Zip'
+---
diff --git a/docs/players/creating-bots/img/agent-builder/create-with-agent-builder.png b/docs/players/creating-bots/img/agent-builder/create-with-agent-builder.png
diff --git a/docs/players/creating-bots/img/agent-builder/default-tree.png b/docs/players/creating-bots/img/agent-builder/default-tree.png
diff --git a/docs/players/creating-bots/img/agent-builder/edit-node.png b/docs/players/creating-bots/img/agent-builder/edit-node.png
diff --git a/docs/players/creating-bots/img/agent-builder/example-tree-1.png b/docs/players/creating-bots/img/agent-builder/example-tree-1.png
diff --git a/docs/players/creating-bots/img/agent-builder/example-tree-2.png b/docs/players/creating-bots/img/agent-builder/example-tree-2.png
diff --git a/docs/players/creating-bots/img/agent-builder/generate-code.png b/docs/players/creating-bots/img/agent-builder/generate-code.png
diff --git a/docs/players/creating-bots/img/agent-builder/load-tree.png b/docs/players/creating-bots/img/agent-builder/load-tree.png
diff --git a/docs/players/creating-bots/img/agent-builder/new-action-node.png b/docs/players/creating-bots/img/agent-builder/new-action-node.png
diff --git a/docs/players/creating-bots/img/agent-builder/open-agent-builder.png b/docs/players/creating-bots/img/agent-builder/open-agent-builder.png
diff --git a/docs/players/creating-bots/img/agent-builder/save-tree.png b/docs/players/creating-bots/img/agent-builder/save-tree.png
diff --git a/docs/players/creating-bots/img/agent-builder/select-node-type.png b/docs/players/creating-bots/img/agent-builder/select-node-type.png
diff --git a/docs/players/creating-bots/img/bot-creation-options.png b/docs/players/creating-bots/img/bot-creation-options.png
diff --git a/docs/players/creating-bots/img/create-bot-button.png b/docs/players/creating-bots/img/create-bot-button.png
diff --git a/docs/players/creating-bots/img/finish-creating-bot.png b/docs/players/creating-bots/img/finish-creating-bot.png
diff --git a/docs/players/creating-bots/img/github/clone-template.png b/docs/players/creating-bots/img/github/clone-template.png
diff --git a/docs/players/creating-bots/img/github/select-repositories.png b/docs/players/creating-bots/img/github/select-repositories.png
diff --git a/docs/players/creating-bots/img/install-github-app.png b/docs/players/creating-bots/img/install-github-app.png
diff --git a/docs/players/creating-bots/img/refresh-repositories.png b/docs/players/creating-bots/img/refresh-repositories.png
diff --git a/docs/players/creating-bots/overview.md b/docs/players/creating-bots/overview.md
@@ -0,0 +1,63 @@
+---
+sidebar_label: 'Overview'
+---
+
+# Overview
+
+Regression Games offers multiple tools for creating and developing AIs - from block-style programming interfaces
+to flexible code libraries that allow programmers of any skill-level to bring their imaginations to (virtual) life.
+
+## GitHub
+
+Regression Games uses [GitHub](https://github.com/) to save, load, and version your AIs.
+Our platform detects changes to your AI as soon as you push them to GitHub, which allows your AI to refresh itself and display new behaviors in real-time.
+The majority of our development tools rely on access to GitHub and therefore will be unavailable to users without a valid account linked to Regression Games.
+
+However, we do offer alternatives to users who prefer not to use GitHub such as [uploading your AI as a .zip file](TODO-REG-1023:-Add-section-and-link-here).
+For this method, you can skip right to our sections on [writing your own AI code](TODO-REG-1035:-Add-section-and-link-here) and [uploading it to our platform](TODO-REG-1023:-Add-section-and-link-here).
+
+## Creating a New AI
+
+### Creating a GitHub Repository
+
+AIs are created and managed within the [Bot Manager](https://play.regression.gg/bots). Click the "Create Bot" button and select one of several creation options.
+For the purpose of this demonstration, we'll keep the default option selected, but the process will be nearly identical for most options in this list.
+
+![Create new AI](./img/create-bot-button.png)
+![Select Creation Option](./img/bot-creation-options.png)
+
+When you confirm your selection, Regression Games will open a new tab in your browser and redirect you to GitHub to create a new repository.
+This repository will represent the AI you're about to create, and Regression Games will access this repository whenever you queue your new AI for a match.
+Give it a name, continue, and wait for GitHub to finish creating it.
+
+![Clone Template](./img/github/clone-template.png)
+
+### Granting Access to Repository Contents
+
+Regression Games values the security and comfort of our users.
+We can see which repositories you have access to, but we can't read contents from or write contents to any repositories under your GitHub account by default.
+Instead, you'll need to tell us which ones we're allowed to access.
+To do this, return to the Regression Games tab in your browser and follow the green link under "Git Settings".
+This will take you back to GitHub to authorize the Regression Games app on your GitHub Account.
+
+If you don't want to repeat this step for every AI you create, you can select the "All repositories" option.
+If you want to explicitly restrict Regression Games to relevant repositories, then find your new repository under "Only select repositories."
+Choose either of these options then click "Install."
+
+![Grant GitHub Access](./img/install-github-app.png)
+![Select GitHub Repositories](./img/github/select-repositories.png)
+
+### Finish Setup
+
+Back in the Regression Games tab in your browser, refresh the repositories list, find your new AI repository, and select it.
+Lastly, name your AI - this is the name other players will see in-game. You can also give it an optional description to help identify it from other AIs you'll create.
+Finally, click the "Create Bot" button.
+
+![Refresh Repositories](./img/refresh-repositories.png)
+![Finish Bot Creation](./img/finish-creating-bot.png)
+
+### Next Steps
+
+Depending on the type of AI you've created, you'll either be returned to the Bot Manager where you can see a complete list of your AIs,
+or you'll be redirected to a new page to interact with one of our AI development tools.
+Continue through this section to learn about all of our development tools and how to use them, or how to program your AI by hand using our code libraries.
diff --git a/docs/players/creating-bots/programming-bots.md b/docs/players/creating-bots/programming-bots.md
diff --git a/docs/players/creating-bots/starter-templates.md b/docs/players/creating-bots/starter-templates.md
diff --git a/sidebars.js b/sidebars.js
@@ -41,6 +41,20 @@ const sidebars = {
         },
       ]
     },
+    {
+      type: 'category',
+      label: 'Creating AIs',
+      items: [
+        'players/creating-bots/overview',
+        'players/creating-bots/blockly',
+        'players/creating-bots/agent-builder',
+        {
+          type: 'category',
+          label: 'Writing Your Own Code',
+          items: ['players/creating-bots/coding/updating-your-ai', 'players/creating-bots/coding/upload-zip']
+        }
+      ]
+    },
     'players/faq'
   ],