Add minimal AI coding instructions

[unfiv]

Proposal: Add structured AI assistant context (docs/ai-instructions.md) to prevent legacy hallucinations and improve DX

Hi! Would Axmol maintainers be open to a small docs/ai-instructions.md file for AI coding assistants?

Motivation

• AI coding tools are heavily used today, but they constantly hallucinate legacy Cocos2d-x APIs (cocos2d:: namespace, deprecated macros) due to 10 years of old internet data.
• Axmol has great human-facing docs, but lacks a short, machine-readable entry point to keep LLMs aligned with modern Axmol C++17/20 idioms.
• A minimal instruction file would drastically reduce AI-generated hallucinations in PRs, risky edits to third-party code, and broken platform templates.

Location Options Considered

Before proposing this path, I evaluated several approaches used across the industry:

1. .github/copilot-instructions.md: Too vendor-specific. It works well for GitHub Copilot but ignores developers using Claude, Cursor, Aider, or Windsurf.
2. AGENTS.md / CLAUDE.md in root: Highly visible, but clutters the repository root with files tied to specific external AI workflows.
3. docs/ai-instructions.md (Chosen): The most agnostic and clean solution. It treats AI context as standard project documentation. Any AI tool can be easily pointed to this path, keeping the repository root completely tidy.

Suggested Scope

• Keep it concise and engine-maintainer focused.
• Enforce Axmol identity: Explicitly instruct LLMs to use the ax:: namespace, AX_CREATE_FUNC, and modern memory management.
• List preferred build/test entry points for verification.
• Document high-risk areas to avoid (e.g., modifying 3rdparty, altering generated templates, breaking platform glue).
• Avoid any game-project-specific rules.

Real-World Examples

• FOnline Engine: Uses an AGENTS.md linked from the README to guide AI-assisted contributors: https://github.com/cvet/fonline
• VibeUE: Ships AGENTS.md.sample for Unreal Engine integration to bootstrap developer environments: https://github.com/kevinpbuckley/VibeUE
• godogen: Publishes engine-focused game repositories pre-configured with AGENTS.md: https://github.com/htdt/godogen

(Note: I checked the Axmol dev branch and confirmed no AI-targeted guidance currently exists in any of these paths).

If maintainers prefer a different name or want to mirror this content into tool-specific paths later, I am happy to adjust. I can submit a clean, minimal PR with zero changes to actual engine code or build scripts.

What are your thoughts on adding this DX upgrade?

[halx99]

I agree add docs/ai-instructions.md , you can submit a PR

[rh101]

@halx99 It may be a good idea to also add an AI policy to the project to help limit auto-generated low-quality and pointless PRs from being submitted, and to detail how such PRs will be treated (ie. such as being closed without review).

My concern is that if such PRs were allowed, this project may become overwhelmed by such PRs, becoming a drain on the time and resources of yourself and the contributors, while also adding unnecessary spam to anyone who has notifications turned on by following the project.

[halx99]

docs/ai-instructions.md

---

Axmol Engine AI Coding Instructions

This file provides critical context and constraints for AI coding assistants working on the Axmol Engine repository. Read and strictly follow these rules to prevent legacy code hallucination and ensure architectural consistency.

---

1. Project Identity & Context

• Axmol is NOT Cocos2d-x: Axmol is a modern, high-performance, cross-platform C++17/20 game engine evolved from Cocos2d-x.
• Zero Legacy Tolerance: Do NOT generate legacy Cocos2d-x code, namespaces, or deprecated preprocessor macros.
• Primary Tech Stack: Modern C++ (C++17/20), CMake build system, and a modern cross-platform Rendering Hardware Interface (RHI) supporting Metal, Vulkan, and D3D12.

---

2. Code Style & Modern C++ Idioms

Namespaces & Naming Conventions

Type	Modern Axmol Standard (DO USE)	Legacy/Deprecated (NEVER USE)
Namespace	ax::	cocos2d::
Core Macros	AX_CREATE_FUNC(...), AX_SAFE_RELEASE(...)	CREATE_FUNC(...), CC_SAFE_RELEASE(...)
Logging	AXLOGD(...), AXLOGI(...), AXLOGW(...), AXLOGE(...)	CCLOG(...)
Types	ax::Object, ax::Node, ax::Vector<T>	cocos2d::Ref, cocos2d::CCNode, cocos2d::Vector<T>

Modern C++ Conventions

• Memory Management: Prefer standard RAII, std::unique_ptr, and std::shared_ptr for non-engine lifecycle objects. For nodes and objects inheriting from ax::Object, use the engine's built-in reference counting (retain(), release(), autorelease()) via utils::createInstance<XXX>(...), A class template: ax::WeakPtr for ax::Object also introduced since axmol-v3.
• Standard Library: Favor standard container and algorithm implementations over custom legacy structures where appropriate.

---

3. Architecture & Rendering Constraints (RHI)

• Modern Backend: Axmol utilizes an abstract Rendering Hardware Interface (RHI). Do not assume fixed OpenGL/GLES pipelines.
• State Management: When writing or modifying rendering components, always comply with the modern RHI pipeline states, commands, and explicit descriptor binding patterns.
• Low-Level Subsystems: Exercise extreme caution when modifying memory allocation, multi-threading primitives, or low-level graphics driver backends.

---

4. Guardrails & Repository Boundaries

Do NOT Modify Without Explicit Permission:

1. 3rdparty/ Directory: Never modify vendored third-party libraries directly. Any adjustments must be done via official updates or clean patches.
2. Platform-Specific Glue (axmol/platform/): Be meticulous with platform-specific entry points (Android JNI, iOS Objective-C++ wrappers, Windows Win32 loops). Ensure alignment with requirements like Android 16KB memory page alignment where applicable.
3. Generated Templates: Do not alter the base structure of project creation templates unless fixing a template-specific bug.

Build System Guidelines:

• All build configurations must use modern, target-based CMake syntax (target_link_libraries, target_include_directories). Avoid global pollution using link_libraries or include_directories.

---

5. Verification Checklist for AI Output

Before presenting any code snippet or Pull Request contribution, verify:

• Is the code completely free of the cocos2d:: namespace?
• Have all macros been migrated to the AX_ prefix?
• Does it compile cleanly under C++17/20 standard?
• Are all memory management patterns safe and free from dangling raw pointers?

[halx99]

docs/ai-policy.md

---

Axmol Engine AI Contribution Policy

To maintain the high quality, performance, and stability of the Axmol Engine, we welcome all meaningful contributions from the community. With the rapid adoption of generative AI tools, we want to proactively establish clear boundaries to ensure AI assistance enhances—rather than degrades—the project's development workflow.

Managing a complex, cross-platform C++17/20 game engine requires significant maintainer time and code-review bandwidth. To prevent future resource drain and avoid notification spam for project watchers, we enforce the following policy regarding AI-assisted and AI-generated content.

---

1. Core Philosophy

• AI is a Tool, Not a Contributor: AI can assist you, but you (the human) are entirely responsible for the code you submit.
• Human Accountability: Every line of code submitted must be thoroughly understood, manually audited, and locally verified by the author.
• Respect Maintainer Bandwidth: "Drive-by" PRs generated with a single prompt to "fix bugs" or perform sweeping "refactorings" without a deep understanding of the engine's architecture will be rejected.

---

2. Acceptable vs. Unacceptable Use

Acceptable Use ✅

• Using AI assistants (Cursor, Copilot, Claude, Gemini, etc.) inside your local IDE to speed up typing, generate boilerplate, or explain existing engine patterns.
• Aligning your local AI workspace context using the repository's docs/ai-instructions.md to ensure it targets modern ax:: namespaces and C++17/20 paradigms.
• Manually reviewing, modifying, and locally compiling every line of AI-suggested code before committing.

Unacceptable Use ❌

• Raw Copy-Pasting: Submitting AI-generated code snippets directly without manual verification, proper testing, or local compilation.
• Automated/Drive-By PRs: Submitting PRs generated by automated scraping tools, external bots, or mass-PR generation scripts.
• Hallucinated Refactoring: Submitting PRs that "fix" non-existent issues, introduce hallucinated APIs, or use legacy Cocos2d-x structures (cocos2d::).
• Unverifiable Submissions: Submitting complex changes to core subsystems (RHI, platform-specific glue, memory management) where the author cannot explain why the change works or how it impacts performance.

---

3. How We Identify Low-Quality AI PRs

Maintainers look for specific red flags that indicate an unverified, AI-dumped submission:

1. Hallucinated APIs or Comments: Use of methods, macros, or properties that do not exist in Axmol (often falling back to old Cocos2d-x names or entirely fictional structures).
2. Generic/AI-Style Descriptions: PR descriptions using overly formal, repetitive, or generic summaries (e.g., "This PR enhances modularity and robustness by optimizing critical variables...").
3. Syntax or Logical Flaws: Code that fundamentally breaks C++ memory models, fails to compile via CMake, or introduces obvious race conditions.
4. Inability to Explain Changes: When asked for clarification on review comments, the author gives vague, generic answers or is unable to provide technical depth.

---

4. Policy Enforcement & Consequences

To maintain a clean repository and protect contributor resources, the following actions will be taken for any PR suspected of violating this policy:

• Immediate Closure: Any PR identified as a raw, low-quality, or automated AI submission will be closed immediately without a formal code review.
• No Argument Triage: Maintainers will mark the PR as spam or invalid and close the thread. We will not spend time debug-proving why an AI-generated snippet is incorrect if the author hasn't done the basic work of compiling and testing it first.

---

5. Submission Checklist for Contributors

To ensure your PR is well-received, please confirm the following before submitting:

• Local Verification: I have compiled the engine cleanly with CMake using this patch.
• Platform Testing: I have verified this change on at least one target platform (e.g., Windows, Android, iOS, macOS, Linux).
• Ownership: I fully understand every line of code submitted and am prepared to maintain or modify it during review.
• No Legacy Code: I have checked that no legacy Cocos2d-x namespaces (cocos2d::) or deprecated macros have been introduced.

---

Thank you for respecting the Axmol community, our maintainers' time, and the engineering standards of this project!

[solan-solan]

I really don't want to flame in this topic, but don't know where to write else. All universal engines like unreal(for mobile)/unity/godot still use opengl. From one side it is done to support millions of existing gpu. But the reason can be more deep. What about the fact that opengl is well known and time tested backend like no one beneath other? Especially for mobiles where vulkan can be not so stable as desired since there are many gpu developers and the technology is rather early. As example there were issues when i play rdr2 some years ago on PC using vulkan. Now it should be ok i believe.

Or may me modern backends can provide some perfect boost of performance which human can to notice? Even in our tests.
I do not say that it is mistake to shift to modern backends. I just say that it is dangerous to do it headlong, and looking just forward.

[halx99]

I really don't want to flame in this topic, but don't know where to write else. All universal engines like unreal(for mobile)/unity/godot still use opengl. From one side it is done to support millions of existing gpu. But the reason can be more deep. What about the fact that opengl is well known and time tested backend like no one beneath other? Especially for mobiles where vulkan can be not so stable as desired since there are many gpu developers and the technology is rather early. As example there were issues when i play rdr2 some years ago on PC using vulkan. Now it should be ok i believe.

Or may me modern backends can provide some perfect boost of performance which human can to notice? Even in our tests. I do not say that it is mistake to shift to modern backends. I just say that it is dangerous to do it headlong, and looking just forward.

On Windows, Android, and Linux, OpenGL is used as the default backend when -DAX_RENDER_API=xxx is not explicitly specified, since Vulkan is not included in the final binary build.

[solan-solan]

Yes thanks, and it is the best configuration for my case of engine using for now.

I just commented to this statements:

Modern Backend: Axmol utilizes an abstract Rendering Hardware Interface (RHI). Do not assume fixed OpenGL/GLES pipelines.
State Management: When writing or modifying rendering components, always comply with the modern RHI pipeline states, commands, and explicit descriptor binding patterns.
Low-Level Subsystems: Exercise extreme caution when modifying memory allocation, multi-threading primitives, or low-level graphics driver backends.

For my understanding since RHI supports opengl already it is quite possible to save it robustness while new backends will improved.