diff --git a/docs/gdevelop5/interface/ai/agent/index.md b/docs/gdevelop5/interface/ai/agent/index.md deleted file mode 100644 index 4f2ba246f82..00000000000 --- a/docs/gdevelop5/interface/ai/agent/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Build with AI ---- -# Build with AI: the AI agent - -The **AI agent** is an AI designed specifically to help with game implementation with GDevelop. It helps discover offical extensions and organize the architecture (global/scene) of game elements depending on the project's needs. - -![A conversation with the AI agent building a feature in a game](./ai-agent-conversation.png) - -## What the AI agent can build for you - -The AI agent has knowledge of all GDevelop features and official reviewed extensions. It also has a view of your whole game, and can inspect your game events or scenes if necessary. - -The AI agent is good for: - -- Doing simple changes ("Make object_X 25% bigger"), -- Creating game mechanics ("Make an enemy that shoots the player once it's within a 20px reach"), -- Experimenting ("Make the key move away from the player when they try to reach it") -- Learning new concepts - by studying the events that the AI has written and how does it resolve your implementation requests. - -The AI will reply in a few seconds after your request. It will then progressively take actions in your game. This can be: - -- Creating a scene, -- Adding objects, -- Adding behaviors to an object, -- Creating or modifying events to build the logic of your game, -- Placing game objects on the scene, -- Creating global or scene elements, etc. - -## How agent implementations work - -The AI will try to fulfill the instructions in your prompt as much as it can. - -For more complex requests, the AI will first display a **plan** — a numbered list of tasks it intends to carry out — before starting work. Each task in the plan shows its current status (pending, in progress, or done). You can expand a task to see the detailed actions it performed. This makes it easier to follow along and spot any steps that went in an unexpected direction. - -As it works on your request, it will show a step-by-step implementation summary of everything it is doing. Some steps can also have extra details you can inspect. In the cases of dealing with a hard to fulfill request, some implementation task could fail (for example: generating complex, heavy dependent game logic). In these cases, the AI agent will move foreward and try alternative ways to continue. - -!!! note - - As all AIs in the market, answers might not be perfect. From time to time the agent can confuse some concepts, misunderstand your game or lack clarity on what you're trying to do. Always verify its answers, and use them as suggestions rather than truths. - **Always double check what the AI does.** Move foreward as long as its implementations are useful, or pause and rework the unuseful bits it has created. - - -You can continue the conversation by asking follow-up requests. **We strongly recommend to use the "[Ask](/gdevelop5/interface/ai/agent/)" mode to model the next steps of the project**. This will give you more visibility on the agent's reasoning and will save you credits if the plan has flaws. - - If you want to switch topics or ask something unrelated, click **"Start a new chat"** — this helps the AI better focus on your new request. - -!!! note - - High AI demand can temporarily slow processing down or prevent the AI to give a proper response. In that case — don’t worry — you won’t be charged any credits. - -## How to use it (good practices) - -Before using the AI agent, **make sure to save your project** or make a working copy to prevent any undesired changes. In the future, cloud projects will support automatic restore versioning points. - -Here are a few best practices to work with the AI agent: - -- **Be highly specific in your instructions:** Describe what you want to create followed by how you'd like it to behave. Write as if you were explaining your idea to a developer who has never seen your game before. Use clear language, describe specific values, specify what you *want* to change and what you *do not* want to change. -- **Plan your mechanics before asking the agent to build them:** Use the "[Ask](/gdevelop5/interface/ai/chat/)" mode to have the AI suggest a plan to implement. Chat with it to make sure it has understood your scope before switching to Build mode. -- **Use one chat per task:** When you’ve finished an implementation task, start a new conversation. This keeps things focused and avoids confusing the AI with unrelated details. -- **Keep an eye on what the AI is doing:** If the implementation plan starts going off-track, you can stop the AI by clicking the **Stop** button. Once stopped, the AI will show a "Stopped. Ready when you are." status and wait for your next message. -- **Expect variations:** Results may differ from one attempt to another. You can try to rephrase your requests for better outcomes. Feel free to document your used promts as well as their results to fine-tune your process. - -## Cost of an AI request - -"Build" mode requests require more credits than "Ask" conversations. Agent's actions could be between 15 to 20 credits depending on the complexity of the implementation, the number of events created, and the number of documentation the AI has to "study" to give an answer. - -As a rule of thumb, a package of 500 credits usually represents 60 to 100 requests to the AI. -Each GDevelop account starts with a few **free AI credits**. If you have a GDevelop Silver, Gold or Pro subscription, you’ll receive more every week: 200 with Silver, 1000 with Gold and 3000 with Pro. - -!!! tip - - If you've run out of free AI requests you can wait for them to reset every Sunday at 23:50 UTC, upgrade your [GDevelop Subscription](https://editor.gdevelop.io/?initial-dialog=subscription) to get more AI requests, or get more [GDevelop credits](https://editor.gdevelop.io/?initial-dialog=credits-purchase). - - -**Monitoring credit usage** - -The interface displays the number of AI requests left in the bottom right of the chat's input. Hover or tap the "question" button to see credit reset time. - -Prioritizing the "[Ask](/gdevelop5/interface/ai/chat/)" mode over "Build" mode will save you credits by reducing implementation misunderstanding from the AI. Consider planning your implementations before executing them. - -## How to improve the AI - -**GDevelop is not using any projects from the community to train the AI**. - -This is why the only way to improve it is by rating the AI’s answers with a 👍 or 👎: positive ratings will signal the AI to follow that rationale. Negative feedback will nudge the GDevelop team that the answer wasn't correct. - -In the case of negative feedback, adding context to why the answer wasn't correct will help the engineers stir the AI to the right direction. diff --git a/docs/gdevelop5/interface/ai/agent/ai-agent-conversation.png b/docs/gdevelop5/interface/ai/ai-conversation.png similarity index 100% rename from docs/gdevelop5/interface/ai/agent/ai-agent-conversation.png rename to docs/gdevelop5/interface/ai/ai-conversation.png diff --git a/docs/gdevelop5/interface/ai/chat/ai-chat-conversation.png b/docs/gdevelop5/interface/ai/chat/ai-chat-conversation.png deleted file mode 100644 index 43cd2bde46f..00000000000 Binary files a/docs/gdevelop5/interface/ai/chat/ai-chat-conversation.png and /dev/null differ diff --git a/docs/gdevelop5/interface/ai/chat/index.md b/docs/gdevelop5/interface/ai/chat/index.md deleted file mode 100644 index f10ebf99ac2..00000000000 --- a/docs/gdevelop5/interface/ai/chat/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Chat with AI ---- -# Ask the AI: the AI helper - -The **AI chat** is designed specifically to answer questions about game creation, help with brainstorming ideas and give GDevelop technical advice. It helps discover extensions or features, and explain how to implement new mechanics. - -Unlike Chat GPT or Gemini, GDevelop's AI can see your project's information which improves its understanding of your requests. - -![A conversation with the AI chat](./ai-chat-conversation.png) - -## How to use it (good practices) - -The "Ask" mode can be used as an idea generator, a "how do I" specialist, a GDevelop teacher or a project planner. -For better implementation results here are some tips: - -- **Create a good prompt, be specific:** Start describing what you want to create followed by how you'd like it to behave. Be as specific as possible with values, gravity, or how the mechanic needs to feel for the player. - -- **Ask step by step:** Ask ordered requests and questions and take it from there. Keep adding information, knowledge or expectations that the AI could use to give you a better answer. - -- **Plan before execution:** Use the "Ask" mode to plan your desired implementation before switching to [Build mode](). This will consume less credits. - -The AI will reply in a few seconds. Answers often include links to helpful resources, extensions, behaviors, and relevant GDevelop concepts like actions or conditions. - -You can continue the conversation with the chat by asking follow-up questions. - -!!! note - - As all AIs in the market, answers might not be perfect. From time to time it can confuse some concepts, misunderstand your game or lack clarity on what you're trying to do. - - Always verify its answers, and use them as suggestions rather than truths. If you'd like to improve your game development knowledge and your use of GDevelop follow the **[GDevelop Essentials Course](https://gdevelop.io/academy)**. - - -## What the AI chat can do - -**The AI understands all built-in GDevelop features and official reviewed extensions**. When active, it has access to your game's logic, game architecture and object configuration. Its knowledge is fed with: - -- General wiki documentation, -- Extension and behavior documentation, -- The scenes and objects in your game, -- Objects' behaviors and other values, -- Events of your game scene, -- Global and scene elements in your game. - -**What it cannot do** - -The AI has **no access** to any personal details like your username, profile information, cloud projects, leaderboards, analytics or other personal detail from your user account. **None of the community's projects have been used to train the AI**. - -Its technical limitations are the following: - -- It cannot scrap your projects for AI training, -- Search the internet, -- Make changes to your project (for that check the [Build](/gdevelop5/interface/ai/agent/) function). - - -## Cost of AI questions - -"Ask" mode questions require less credits than "[Build](/gdevelop5/interface/ai/agent/)" questions. Answers could be between 3 to 5 credits depending on the complexity of the answer and the number of ressources the AI has to "read" to give an answer. - -!!! note - If you've run out of free AI requests you can wait for them to reset every Sunday at 23:50 UTC, upgrade your [GDevelop Subscription](https://editor.gdevelop.io/?initial-dialog=subscription) to get more AI requests, or [get more GDevelop credits](https://editor.gdevelop.io/?initial-dialog=credits-purchase). - -**Monitoring credit usage** - -The interface displays the number of AI requests left in the bottom right of the chat's input. Hover or tap the "question" button to see credit reset time. - -Prioritizing the "Ask" mode over "Build" mode will save you credits by reducing implementation misunderstanding from the AI. Consider planning your implementations before executing them. - -## How to improve the AI - -You can rate the AI’s answers with a 👍 or 👎. Positive ratings will signal the AI to follow that rationale. Negative feedback will nudge the GDevelop team that the answer wasn't correct. - -In the case of negative feedback, adding context to why the answer wasn't correct will help the engineers stir the AI to the right direction. - -!!! note - High AI demand can temporarily slow processing down or prevent the AI to give a proper response. In that case — don’t worry — you won’t be charged any credits. diff --git a/docs/gdevelop5/interface/ai/index.md b/docs/gdevelop5/interface/ai/index.md index 8432a9211fd..4fda3543810 100644 --- a/docs/gdevelop5/interface/ai/index.md +++ b/docs/gdevelop5/interface/ai/index.md @@ -1,81 +1,149 @@ --- -title: Ask AI (build/chat with AI) +title: Ask AI (build and chat with AI) --- -# Ask AI: Build your game with AI -Unlike general-purpose AI tools like ChatGPT, Claude, or Google Gemini, GDevelop AI is **tailored for game creation**. It knows how GDevelop works, it has access to your game's objects configuration, events and context. +# Ask AI: build and chat with your game's AI + +GDevelop AI is a **creation agent for making games**: describe what you want in plain language, and it will answer your questions, brainstorm ideas, and build mechanics directly in your project. Unlike general-purpose tools like ChatGPT, Claude or Google Gemini, it's specialised for GDevelop — it knows how the engine works and can read your game's objects, behaviors, variables and events to understand what you're working on. + It can help you: -- Understand features and how to use them -- Build specific mechanics or systems -- Help fix small implementation errors -- Explore, brainstorm and bring new ideas to life +- Understand features and how to use them, +- Build specific mechanics or whole systems, +- Fix small implementation mistakes, +- Explore, brainstorm and bring new ideas to life. !!! tip - Think of it as an always available mentor and creative collaborator that speaks GDevelop fluently. + Think of it as an always-available mentor and creative collaborator that speaks GDevelop fluently. + +Click on **Ask AI** in the top-right corner of GDevelop to open it. -Click on **Ask AI** on the top-right corner (1) of GDevelop to open the AI chat. ![Open Ask AI](./Askai-Open.png) -## How it works +You simply describe what you want in plain language, and the AI decides whether to answer, explain, or make changes in your project. + +![A conversation where the AI builds a feature in a game](./ai-conversation.png) + +The AI knows all built-in GDevelop features and the official, reviewed extensions. It does **not** know about community extensions unless they've been approved by the GDevelop team. + +## What the AI can build for you + +When it builds, the AI can take many concrete actions in your game, such as: + +- Creating scenes, +- Adding objects and placing them in a scene, +- Adding behaviors to objects, +- Creating or modifying events to build your game's logic, +- Creating global or scene-wide elements, +- Finding and installing suitable official extensions or assets. + +!!! note + + It's well suited for: + + - Simple changes — *"Make object_X 25% bigger"*, + - Game mechanics — *"Make an enemy that shoots the player once it's within 20px"*, + - Experiments — *"Make the key move away from the player when they try to reach it"*, + - Learning — by reading the events the AI writes, you can see how a mechanic is actually built. + +## How the AI works on your request + +The AI replies within a few seconds, then gets to work. Rather than doing everything in one block, it **breaks your request into smaller pieces of work** and tackles them one after another. You'll see these as short steps in the conversation, for example *"Exploring the game"*, *"Inspecting the game structure"*, *"Editing the game"*, or *"Searching the asset store"*. + +For more involved requests, the AI first lays out a **plan**: a numbered list of the steps it intends to follow. Each step shows its status (pending, in progress, or done), and you can expand a step to see the detailed actions it performed. This makes it easy to follow along and notice if something heads in an unexpected direction. + +If a step turns out to be difficult (for example, building complex, heavily interconnected logic), it may not fully succeed. When that happens, the AI moves forward and tries an alternative approach to keep going. + +!!! note + + Like all AI tools, the answers aren't always perfect. Now and then the AI can confuse a concept, misunderstand your game, or miss what you intended. **Always double-check what it does.** Keep its work when it's useful, and adjust or undo the parts that aren't. + +## Choosing how hard the AI thinks (reasoning level) -The AI understands all built-in GDevelop features, and official reviewed extensions. However, its knowledge does not include community extensions unless they’ve been approved by the GDevelop team. -Context is everything to assure good AI results. To improve its suggestions, the AI can read the content of your project: object's configuration, behaviors, variables and event sheet. +You can pick a **reasoning level** for the AI, next to the message box. A higher level means the AI thinks more deeply before acting — which can give better results on tricky requests, but takes a bit longer and uses more credits. -The AI has two modes: +- **Medium** — available to everyone, a good balance for most requests. +- **High** — available with a **Gold** or **Pro** subscription, for more complex builds. +- **Maximum** — available with a **Pro** subscription, for the most demanding requests. -- **[Ask a question (AI chat)](./chat)**: silimar to Chat GPT or Gemini conversations. The AI will answer questions on game development, GDevelop usage, and idea brainstorming. This mode is recommended to learn the tool and define the implementation plan before using the Build mode. -- **[Build for me (AI agent)](./agent)**: similar to Cursor or V0. The AI will build your implementation requests inside your game. This can range from simple changes (example: "Make X object 20% bigger") to more complex requests ("Create an enemy that starts shooting arrows when the player comes 20px near it"). +Start with Medium for everyday tasks, and raise the level only when a request is large or the AI is struggling to get something right. -For mor information on credit consumption and good practices: -[Learn more about the GDevelop AI agent](./agent){ .md-button .md-button--primary .full-width } +## "Auto edit": chatting safely or letting the AI build -[Learn more about the GDevelop AI chat](./chat){ .md-button .full-width } +Next to the message box you'll find an **Auto edit** switch: + +- **Auto edit on** (the default): the AI applies changes to your project directly as it works. This is the best setting when you want it to build something for you. +- **Auto edit off**: the AI can still read your project, answer and suggest, but it will **ask for your confirmation before each change**. This is perfect for brainstorming, planning, or asking questions when you don't want to risk any modification to your game. + +When Auto edit is off and the AI wants to make a change, it shows a short prompt with the change it intends to make. You can choose **Yes, just this change**, **Yes, and enable auto-edit** (to stop being asked for the rest of the conversation), or **No**. + +!!! tip + + Turn Auto edit **off** while you're still figuring out *what* you want. Once you and the AI agree on a plan, turn it **on** and let it build. This avoids unwanted changes and saves credits. + +## Restoring your project to an earlier point + +For **cloud projects**, GDevelop automatically saves a restore point **before** each of your messages and AI requests. If a build went in a direction you don't like, you can roll back: in the conversation, find the saved point (shown as **Project saved**) and use the **restore** button to bring your project back to that state. + +!!! warning + + Restoring overwrites the current project state with the saved one, so use it when you genuinely want to discard the changes made since that point. GDevelop will ask you to confirm before restoring. + +If you're working on a **local project** (saved on your computer) rather than a cloud project, this automatic restore isn't available — so it's a good idea to **save your project or keep a working copy** before asking the AI to make big changes. + +## Pausing and starting fresh + +- **Stop**: if the AI starts going off-track, click **Stop** to pause it. It will wait for your next message instead of continuing. +- **New chat**: when you've finished a task, start a new conversation. This keeps each chat focused on one topic and helps the AI avoid confusing it with unrelated details. ## Cost of AI requests -An AI request could use 3 to 30 credits depending on the scope. -The number of credits used depends on the work and processing ("thinking") the AI has to do: -- an "Ask" request can be 2 to 5 credits, -- a simple "Build" request to do a small change could use 10 credits while implementations with multiple events could be 16 to 20 credits. +Each request uses some of your **AI usage**, depending on how much work and "thinking" it involves: a quick question costs very little, while building several events at once costs more. The reasoning level also matters — higher levels use more. + +**Monitoring your usage** + +Your remaining AI usage is shown as a **percentage** near the message box (for example, *"You still have 80% left on this week's AI usage"*). Your allowance **resets every week, on Sunday evening** (23:50 UTC). Hover or tap the info icon to see exactly when it resets. !!! tip - Start by using the "Ask" mode to wirte your prompts and define the scope of your desired implementation. Once the AI has a feasible plan switch to "Build mode". This will prevent you from spending unnecessary credits. + Keeping **Auto edit off** while you plan, and only switching it on to build an agreed-upon plan, is the best way to make your weekly usage go further. + +**Getting more AI usage** -## Aquiring credits for AI requests -All accounts starts with a few free AI credits. Once you've used all your free AI credits, you can: +If you've used up your allowance, you can: -- Wait for them to replenish (every Sunday at 23:50 UTC) -- [upgrade]( https://editor.gdevelop.io/?initial-dialog=subscription) to GDevelop premium subscriptions -- [Buy](https://editor.gdevelop.io/?initial-dialog=credits-purchase) additional [GDevelop credits](/gdevelop5/interface/profile/credits/) to get more AI requests -- Give [quality feedback](/gdevelop5/interface/games-dashboard/player-feedback/) to GDevelop creators -- Follow GDevelop accounts on socials and claim the credits through your profile +- Wait for it to reset (every Sunday at 23:50 UTC), +- [Upgrade](https://editor.gdevelop.io/?initial-dialog=subscription) to a GDevelop premium subscription — Silver, Gold and Pro each include more weekly AI usage, +- [Buy](https://editor.gdevelop.io/?initial-dialog=credits-purchase) additional [GDevelop credits](/gdevelop5/interface/profile/credits/), +- Give [quality feedback](/gdevelop5/interface/games-dashboard/player-feedback/) to other GDevelop creators, +- Follow GDevelop on social media and claim credits through your profile. !!! note - A package of 500 credits usually represents 60 to 100 requests to the AI. -**Premium Subscriptions** like GDevelop Silver, Gold or Pro receive more free AI requests every week: 200 with Silver, 1000 with Gold and 3000 with Pro. + High AI demand can occasionally slow things down or prevent a proper response. If that happens — don't worry — you won't be charged for it. +## Good practices + +- **Be specific:** describe *what* you want and *how* it should behave, as if explaining your idea to a developer who has never seen your game. Give concrete values, and say what you *do* and *do not* want changed. +- **Plan before you build:** with Auto edit off, discuss the mechanic and let the AI propose an approach. Once it clearly understands your goal, switch Auto edit on to build it. +- **One chat per task:** start a new conversation for each new feature to keep things focused. +- **Keep an eye on the work:** watch the steps and the plan. If something looks wrong, stop the AI and rephrase. +- **Expect variation:** results can differ between attempts. Rephrasing often helps — and noting down prompts that worked well will sharpen your own process. ## AI privacy -GDevelop AI is built on general purpose Large Language Models (LLMs) that can be adapted, fine tuned or have internally multiple agents working on a request. +GDevelop AI is built on general-purpose Large Language Models (LLMs), which can be adapted, fine-tuned, or coordinate several specialized steps internally to handle a request. -**GDevelop AI is not trained on your accout's files nor individual projects**. -Local and cloud project are only accessible to the AI when the chat is in use. All cloud projects are stored separately from the GDevelop AI infrastructure which prevents it from access them without your request. +**GDevelop AI is not trained on your account's files or your individual projects.** Local and cloud projects are only accessible to the AI while you're actively using it in a conversation. Cloud projects are stored separately from the GDevelop AI infrastructure, which prevents access to them without your request. -**In all cases there is no usage of private data for improving the AI.** +The AI also has **no access** to personal details such as your username, profile information, leaderboards, or analytics. It cannot browse the internet. +**In all cases, your private data is never used to improve the AI.** ## How to improve the AI -You can rate the AI’s answers with a 👍 or 👎. Positive ratings will signal the AI to follow that rationale. Negative feedback will nudge the GDevelop team that the answer wasn't correct. +Because no community projects are used to train it, the main way to improve the AI is to **rate its answers** with a 👍 or 👎. Positive ratings reinforce a good approach; negative feedback flags to the GDevelop team that an answer wasn't right. -In the case of negative feedback, adding context to why the answer wasn't correct will help the engineers stir the AI to the right direction. +When leaving negative feedback, adding a short note on *why* the answer was wrong helps the team steer the AI in the right direction. ![AI report](./AI_report.png) - -!!! note - - High AI demand can temporarily slow processing down or prevent the AI to give a proper response. In that case — don’t worry — you won’t be charged any credits. diff --git a/mkdocs.yml b/mkdocs.yml index 83fa744a7c0..04dbcca4401 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -124,6 +124,8 @@ plugins: "gdevelop5/publishing/android_and_ios/play-store/index.md": "gdevelop5/publishing/android/play-store/index.md" "gdevelop5/publishing/android_and_ios/play-store/upgrading-from-apk-to-aab.md": "gdevelop5/publishing/android/play-store/upgrading-from-apk-to-aab.md" "gdevelop5/interface/ask-ai.md": "gdevelop5/interface/ai/index.md" + "gdevelop5/interface/ai/agent/index.md": "gdevelop5/interface/ai/index.md" + "gdevelop5/interface/ai/chat/index.md": "gdevelop5/interface/ai/index.md" "gdevelop5/interface/scene-editor/events.md": "gdevelop5/interface/events-editor/index.md" # Tutorials "gdevelop5/tutorials/platformer/start.md": "gdevelop5/tutorials/platformer/index.md"