diff --git a/docs/players/creating-bots/agent-builder.md b/docs/players/creating-bots/agent-builder.md index e26a69c8..89af3790 100644 --- a/docs/players/creating-bots/agent-builder.md +++ b/docs/players/creating-bots/agent-builder.md @@ -1,6 +1,130 @@ --- -sidebar_label: 'Using the Agent-Builder' +sidebar_label: 'Using the Agent Builder' --- -# Creating Bots Using the Agent-Builder \ No newline at end of file +# 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` 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 new file mode 100644 index 00000000..0219752a --- /dev/null +++ b/docs/players/creating-bots/coding/updating-your-ai.md @@ -0,0 +1,5 @@ +--- +sidebar_label: 'Updating Your AI' +--- + +# Updating Your AI \ No newline at end of file diff --git a/docs/players/creating-bots/coding/upload-zip.md b/docs/players/creating-bots/coding/upload-zip.md new file mode 100644 index 00000000..96fc8a85 --- /dev/null +++ b/docs/players/creating-bots/coding/upload-zip.md @@ -0,0 +1,3 @@ +--- +sidebar_label: 'Uploading a Zip' +--- \ No newline at end of file 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 new file mode 100644 index 00000000..98fe05b0 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/create-with-agent-builder.png differ diff --git a/docs/players/creating-bots/img/agent-builder/default-tree.png b/docs/players/creating-bots/img/agent-builder/default-tree.png new file mode 100644 index 00000000..f974ce8d Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/default-tree.png differ diff --git a/docs/players/creating-bots/img/agent-builder/edit-node.png b/docs/players/creating-bots/img/agent-builder/edit-node.png new file mode 100644 index 00000000..e1bc7cd3 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/edit-node.png differ 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 new file mode 100644 index 00000000..a8b3c430 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/example-tree-1.png differ 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 new file mode 100644 index 00000000..f5ab5de5 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/example-tree-2.png differ diff --git a/docs/players/creating-bots/img/agent-builder/generate-code.png b/docs/players/creating-bots/img/agent-builder/generate-code.png new file mode 100644 index 00000000..12d30a64 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/generate-code.png differ diff --git a/docs/players/creating-bots/img/agent-builder/load-tree.png b/docs/players/creating-bots/img/agent-builder/load-tree.png new file mode 100644 index 00000000..a574e027 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/load-tree.png differ 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 new file mode 100644 index 00000000..8d5d3ab2 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/new-action-node.png differ 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 new file mode 100644 index 00000000..5dba6dc9 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/open-agent-builder.png differ diff --git a/docs/players/creating-bots/img/agent-builder/save-tree.png b/docs/players/creating-bots/img/agent-builder/save-tree.png new file mode 100644 index 00000000..78b5d1e8 Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/save-tree.png differ 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 new file mode 100644 index 00000000..cc93847c Binary files /dev/null and b/docs/players/creating-bots/img/agent-builder/select-node-type.png differ diff --git a/docs/players/creating-bots/img/bot-creation-options.png b/docs/players/creating-bots/img/bot-creation-options.png new file mode 100644 index 00000000..c417fa44 Binary files /dev/null and b/docs/players/creating-bots/img/bot-creation-options.png differ diff --git a/docs/players/creating-bots/img/create-bot-button.png b/docs/players/creating-bots/img/create-bot-button.png new file mode 100644 index 00000000..49527681 Binary files /dev/null and b/docs/players/creating-bots/img/create-bot-button.png differ diff --git a/docs/players/creating-bots/img/finish-creating-bot.png b/docs/players/creating-bots/img/finish-creating-bot.png new file mode 100644 index 00000000..3bbd2635 Binary files /dev/null and b/docs/players/creating-bots/img/finish-creating-bot.png differ diff --git a/docs/players/creating-bots/img/github/clone-template.png b/docs/players/creating-bots/img/github/clone-template.png new file mode 100644 index 00000000..2c5eaada Binary files /dev/null and b/docs/players/creating-bots/img/github/clone-template.png differ diff --git a/docs/players/creating-bots/img/github/select-repositories.png b/docs/players/creating-bots/img/github/select-repositories.png new file mode 100644 index 00000000..e1e22823 Binary files /dev/null and b/docs/players/creating-bots/img/github/select-repositories.png differ diff --git a/docs/players/creating-bots/img/install-github-app.png b/docs/players/creating-bots/img/install-github-app.png new file mode 100644 index 00000000..e1e1143b Binary files /dev/null and b/docs/players/creating-bots/img/install-github-app.png differ diff --git a/docs/players/creating-bots/img/refresh-repositories.png b/docs/players/creating-bots/img/refresh-repositories.png new file mode 100644 index 00000000..eeb15816 Binary files /dev/null and b/docs/players/creating-bots/img/refresh-repositories.png differ diff --git a/docs/players/creating-bots/overview.md b/docs/players/creating-bots/overview.md new file mode 100644 index 00000000..77cf5e91 --- /dev/null +++ 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 deleted file mode 100644 index 961cc07d..00000000 --- a/docs/players/creating-bots/programming-bots.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_label: 'Programming Your Bot' ---- - -# Programming Your Bot \ No newline at end of file diff --git a/docs/players/creating-bots/starter-templates.md b/docs/players/creating-bots/starter-templates.md deleted file mode 100644 index da054f8a..00000000 --- a/docs/players/creating-bots/starter-templates.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_label: 'Cloning a Starter Templates' ---- - -# Cloning a Starter Template \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index c900dd18..4ef6de53 100644 --- 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' ],