1. Summary of the summary

When working to solve the problem, we should be gaining understanding (of the problem, our available tools, solutions…), not losing it.

Don’t use AI in a way that makes you dumber. Don’t make solutions that are unmaintainable, not understood, badly designed, mixed with hallucinated docs or assumptions.
Do use AI in a way that makes you smarter. Reach the right solution by extra information and reviews (that you understand and agree with), reach it faster by suggestions (that you understand, and can confirm they point you in the right direction).

2. Summary

This page documents required rules when using AI to contribute to Castle Game Engine. It also collects our recommended guidelines when using AI in your own projects.

You are responsible for everything you submit: code, documentation, commit messages, issue/PR descriptions.
Understand everything you submit. Know reasons behind it. Do own research and decision-making.
Be critical of AI suggestions. They may contain hallucinations or unoptimal approaches.
Keep AI conversations private. Don’t clutter issues with your conversations with AI.

A good rule of thumb is to generate smaller, not larger, pieces of code / documentation.

AI-generated larger pieces of code / documentation are often wrong. They confuse you (suggesting further work in a wrong direction), they show hallucinated or deprecated APIs, they do not use recommended approaches (e.g. AI often puts everything in one big program file, which makes application non-cross-platform and ignores our views concept to organize applications), they do not understand the platform-specific and compiler-specific language nuances etc.
Do start with small tasks for AI. Use AI for code completion (and reject without hesitation wrong suggestions). Use agents for smaller tasks, that you have an idea how to solve yourself. Ask questions about the codebase "how is X done" (and check the answer).

3. Introduction

Note

Unlike most of our engine documentation, parts of this text is written in my personal (hi, I’m Michalis) voice, sharing my personal experience. I hope this helps you understand the reasoning behind some of the statements.

Also, I’m sorry it’s a long text. Ironically, being too verbose is also a complaint we often have about AI-generated stuff. I can only hope that my human writing is more entertaining / informative :)

From my conversations with fellow developers, I know we’ve all tried using AI, and we all have our share of success stories and failure stories (cautionary tales).

One of my personal early successes was using AI to help me add Sketchfab Integration to our editor. AI’s knowledge of the Sketchfab API was very helpful, and it was capable of using our TCastleDownload for the task, when instructed to use it.

Since then, I’ve been using AI for many tasks — code completion, code exploration, self reviews… I recognize it’s just a probabilistic machine that repeats, with only a certain probability of being right, the "Internet wisdom" — nothing more, nothing less.
One of my personal failures, quite recent actually (2025), was asking AI for a proof of Pythagorean theorem. AI incorrectly combined a few different ways to go about proving this theorem, and it made a nonsense step in the middle of the proof, temporarily changing the meaning of the symbols and claiming invalid things about the situation. To make matters worse, this incorrect answer from AI looked plausible (if you just scan it quickly without really comprehending each step, you will nod your head and say "yes, that sounds about right"), and it was stated with confidence. Since AI is trained to produce output that sounds plausible and confident.

The educational implications of such AI mistakes are worrying. Think about children who want to learn math and ask AI such a question, perhaps because they didn’t understand the proof their teacher showed during a school lesson, so they come home and ask AI for help. If I were 10 years old and used AI to help me understand the Pythagorean theorem proof, I would conclude "well, one step in this proof doesn’t look right; I’m probably too stupid to understand it". It’s only because I’m older (and more confident in my own math skills) that I can see the reality: "one step in this proof is incorrect; AI is wrong because it’s just a probabilistic machine guessing what to tell me to sound most plausible".

With this introduction, let’s jump into recommendations and rules about using AI to contribute to Castle Game Engine.

Warning

One last disclaimer: This page doesn’t discuss the aspects of AI beyond "using AI to write Pascal code in the context of our engine". We don’t discuss here the fact that AI was trained on copyrighted data (sometimes non-public) and can regurgitate it when asked, without caring about attribution or licensing. Or various clear abuses of AI, like generating spam (such as on our forum). Or the existential dread where does this progress lead, thinking years ahead. Or using AI to make good art (2D or 3D). The topic is broad. Let’s focus for now on how to use what you have, right now, to help you write good code.

4. Requirements

The core rule is that you are responsible for every line of code and every sentence in documentation (in code, in issue/PR descriptions) that you submit. If it’s nonsense or unoptimal, you should make it better.
Do not submit code you don’t understand. If AI has suggested a solution, we expect you to analyze every line of it and adjust if necessary before submitting.

Consider:
- Is the proposed solution the right way to solve the problem? Is this how you would go about it, if you forget about AI for a second?
- Whether it is maintainable (apply software design principles like DRY (Don’t Repeat Yourself) and KISS (Keep It Simple, Stupid)).
- Whether it follows the engine coding conventions and uses the right engine API. And yes, you can help AI by pointing it to our docs. Our manual is in the AsciiDoctor format which is just a text with trivial markup and AI can process it effortlessly.
- Whether it supports all our compilers and platforms. AI is often mistaken about nuances here; our CI/CD helps detect issues.
The same goes for documentation and issue/PR descriptions. Make sure it’s a good documentation, simple, and to the point. Documentation must actually help human developers, not be just "something you had to provide, so you asked AI to produce something that looks plausible, to pass the review".

Especially watch out for overly long and marketing-style statements. We don’t want long documents with emoticons claiming that "this is the best solution in the world". And while being grammatically correct is nice, it’s not the most important thing we look for in a good documentation.

We look for documentation that is precise, practically helpful (no marketing buzzwords, just explain the problem and solution), and concise (shorter is better).

See my own test, using an AI agent to develop MCP where AI did… a useful start, but it required a lot of fixes (to even make this start be correct, as AI tried to extend the test suite, failed, and happily assumed it’s all good; it also implemented 2 solutions, both wrong in different ways, at the beginning). And it’s still far from a useful solution, it cannot be used in a way we need, and it’s only a mockup that isn’t aware of the real project. Yet AI confidently claims in the PR that "This implementation makes Castle Game Engine the first game engine with comprehensive MCP support". It’s a hilariously invalid statement :)
Don’t fill issues with your conversation with AI. This particularly applies to conversations with GitHub Copilot. Yes, GitHub encourages you to use GitHub Copilot in various contexts throughout their website (and maintainers cannot even block it) --- but it’s not a good practice. We don’t want to read your conversation with AI (sometimes filled with hallucinations, sometimes overly verbose and off-topic). If you want to talk with AI or iterate on code with AI, do it in your own space, without distracting other developers . For example, use a text editor that has AI integration. Review AI-proposed changes before anything gets committed.
Don’t respond with AI-generated answers to our questions. We value what you think; we value the real reasons behind the decisions you made. We don’t value AI justifying the changes in an attempt to convince the human reviewer that "it’s good, merge it".

5. Guidelines to use AI successfully (when contributing, or using in your own projects)

You, as a human programmer, must be in charge.
Start by asking AI to help you understand the code.
- Ask AI questions about particular code pieces, small or large.
- Ask AI to find bugs or memory leaks, to proofread your submission.
- Let AI analyze a codebase and describe how things work.
- Use AI to search for things (esp. things that are beyond "grep search"; e.g. you don’t know how it is called, but you know that there’s exists "something that allows to add two 3D vectors"; AI can find it and tell you to var A, B, C: TVector3; A := B + C;).
Still, never trust the answer without double-checking it. Remember my cautionary tale about the Pythagorean theorem above. When the answer is not obvious, AI will hallucinate (tell you a lie) and be confident about it.
Use AI for code completion, i.e. suggestions in text editors. This allows AI to augment deterministic code completion (like from our VS Code extension, which uses Lazarus CodeTools for code completion), and in simple cases, the suggestions may be correct and save you some typing.

Accept suggestions if they make sense. If you look at the suggestion and you can immediately see "yes, that’s exactly what I wanted to type, thanks!".

Reject suggestions if they don’t make sense or you’re not sure what they do or why. Don’t hesitate to reject AI work, and don’t over-analyze AI answers to find "nuggets of truth" in an incorrect answer. AI is just guessing to please you, based on what it was trained on.
Use AI for code reviews. It’s useful to have another set of eyes look at your code changes. Before committing, you can e.g. ask "review uncommitted changes".

Don’t trust blindly the review. If AI recommends this or that change, understand why, check are recommendations suitable in this case, check is it not hallucinating or misunderstanding how to change the code, IOW judge for yourself.

That said, such "extra pair of eyes" is often useful in my experience. Some of the things AI can point out during the review are valid. By addressing (some of) the review notes, I make much better commits.

AI agents should be used with caution and only with full understanding.

Don’t throw a hard task at AI, hoping it will solve it for you in one shot. Split the task into smaller pieces (make a "TODO list" for the agent). Specify the conditions for the task (do X using Y and Z, e.g. "communicate with X using it’s REST API and engine TCastleDownload class", or "introduce a method to class X doing this"). Always consider how to refactor the solution to be simplest and most maintainable. AI output is supposed to be a starting point for you, not the final solution.

Note

Special recommendation applies to starting a new project with AI. Do not tell AI to "just create a new game using Castle Game Engine" — as then it can make a bad starting point, ignoring our views, going against our recommended setup for cross-platform projects, making visual designing impossible etc.

Instead, tell AI to create a new project using castle-engine create empty command-line (see our build tool commands) and then turn this into your desired game.

Note

Don’t worry, visual designing in our editor doesn’t conflict with editing the project with AI agents. Our designs are just JSON files, and agents are capable of modifying these JSONs. So the agents can cooperate with visual designing effectively.

In fact, do not let agents do all the work by writing Pascal code, when instead they should modify design JSON files. The AI agents tend to solve too much tasks by writing Pascal code, because the AI is happy to write long spaghetti boilerplate code. But this is not good for further modification — the effect of setting up components using Pascal code can only be observed at run-time, you cannot edit the design in the editor. Guide the AI to add/modify components by editing our designs (.castle-user-interface, .castle-transform JSON files) when possible.

Look whether there’s an existing solution to your problem outside of AI. For example, create a new project using our editor’s "New Project" feature (instead of asking AI to start a project). Or look into our examples for something similar to what you’re trying to do. Starting from something correct (and using an AI agent to customize the solution for your needs) is better than forcing AI to guess a big solution from scratch.

And again, remember that you are responsible for the solution, both code and documentation. Don’t submit it without reviewing it. Don’t submit any code or documentation that you don’t understand. Don’t use any language constructs that you don’t understand.

Basically, ask AI to "fill the gaps" for you, to help you. If you ask it to do design work (propose a solution for you), be very critical of the answer — maybe it’s a good start, or maybe it requires refactoring to be useful, or maybe it’s best to reject it and try another approach.

6. Guidelines to successfully develop applications using Castle Game Engine, with or without AI

Whether you use AI or not, common recommendations apply:

Learn to use the engine by watching our tutorials, reading our tutorials, and following our manual.
Use the editor to create a new project and see what API the project is using. Think about how you want to extend it. Look in our API documentation to learn what things do.
Start small. Experiment by creating simple games, that seem like "typical use of the engine". Start with the engine’s "New Project" templates. Extend it, reading the necessary documentation along the way.
Use version control. Git is currently the most popular version control system. Using version control allows you to review your own changes and/or changes proposed by AI.

7. See also

In our engine:

We have experimented even with vibe coding for fun, see https://github.com/michaliskambi/castle-vibes/ for the complete code and data, screenshots, and a long README with observations. We’ve made a news post summarizing the conclusions.
See also example situations in the context of Castle Game Engine how AI hallucinations make bad code/docs.

Many other projects have nice guidelines about using AI that we agree with. For example:

More opinions I agree with:

Kurzgesagt video warning about AI slop. There is a real problem of welcoming hallucinations into our knowledge base (Internet).
I do think that one answer is we need search engines trying to "filter out" AI slop (not amplify it). I’m a happy user of Kagi and agree with their POV about LLMs.
Article from Addy Osmani "The 80% Problem in Agentic Coding" is a balanced viewpoint I agree with — highlighting both the hope and the dangers of AI agents in coding.
Interview with Pi devs has lots of valid observations about AI and coding.

To improve this documentation just edit this page and create a pull request to cge-www repository.