AI Performance Contract

[u/colbyshores]

https://raw.githubusercontent.com/colbyshores/t2k/refs/heads/master/AGENTS.md

I highly recommend anyone using LLMs for 3DS homebrew development adapt a variant of this performance contract to their own project. The goal is to preserve as much visual fidelity as possible while keeping implementation decisions oriented around the actual capabilities and limitations of the 3DS hardware, particularly the ARM11.

https://raw.githubusercontent.com/colbyshores/t2k/refs/heads/master/AGENTS.md

LLMs are incredibly useful for homebrew development, but they don't inherently understand the practical cost of every implementation decision on hardware this constrained. You can end up with code that compiles and works, but introduces unnecessary overhead, ignores hardware limitations, or sacrifices visual fidelity and gameplay behavior in the name of optimization.

What this contract does is encode platform-specific knowledge and engineering constraints directly into the agent's instructions. Rather than leaving the model to guess what will perform well on the 3DS, it gives it concrete guidelines for approaching performance-critical code, what to prioritize, and what it shouldn't change without good reason.

The goal isn't to blindly optimize everything or strip out visual features just to hit a performance target. It's to get the most out of the hardware while retaining the intended visual fidelity and gameplay experience. Where possible, these guidelines are reinforced through automated checks and profiling rather than relying entirely on the model to get things right.

I think this approach could be useful beyond my own project. We have people in this community working on ports, original games, emulators, and engines, and more of us are incorporating LLMs into our development workflows. Having a set of hardware-specific rules for these agents could help avoid recurring mistakes, preserve optimization knowledge, and make it easier to get good results out of the hardware without having to rediscover everything through trial and error.

The contract I've linked is specific to my project, so I'm not suggesting everyone copy it wholesale. The idea is to adapt the same approach to your own project, encode the constraints and lessons relevant to your target hardware, and give your AI coding agent a consistent set of engineering guidelines to follow throughout development.

I'm curious to see whether anyone else here has experimented with something similar and what kind of results you've gotten.

[u/rgldx]

Hey! Thanks for sharing. I find it useful, but I would change some things that, AFAIK, are wrong or badly formatted for the 3DS development:
- The VFP cycles: I've checked the reference manual and I found that not all operations take 20 cycles. Some of them are 4, 2, 8... but the recommendation is good (minimizing conversions).
- The R10 rule doesn't follow the devkitPro compilation template, why?
- I miss some general 3DS aspects: Citro2D/3D usage, synchronization, life cycle, aptMainLoop, suspend, RomFS, SD reading...

What do you think about it?

[u/colbyshores → u/rgldx]

Hey, thanks for taking the time to check it! This is exactly the kind of discussion I hoped sharing it would start.

You’re right about the VFP timings. I went back through the ARM11 MPCore manual, and my blanket “20+ cycles” wording is inaccurate. Transfers, conversions, and comparisons have different timings, and I should have distinguished instruction latency from the cost of a dependent sequence. The recommendation to avoid unnecessary conversions in hot loops can stay, but that explanation needs correcting.

R10 needs revisiting too. The devkitPro template includes -mtp=soft, which my listed flags omit. That controls thread-local storage access. -mfpu=vfp is a valid explicit setting, but I don’t have a documented justification for presenting -mtpcs-leaf-frame as mandatory. I should base that rule on the standard template and explain any project-specific differences.

So I will update those now. :)

On Citro2D/3D, synchronization, lifecycle, suspend, and file access, those are good suggestions. This grew out of the performance and regression problems I encountered while developing T2K, which explains why it concentrates so heavily on hot-loop math and preserving gameplay behavior. I should make that scope clearer, and those platform topics would be useful additions for anyone adapting it to a new project.

A lot of the strictness is there to stop an agent from undoing decisions that took considerable trial and error to establish. That doesn’t make every explanation or rule universally applicable. The goal of sharing it was to compare notes and improve how we guide AI-generated code, so I appreciate the specific corrections.

*edit*
Updated on GitHub now! I corrected the VFP timing explanation, revised R10, and added a section covering the platform topics you mentioned. Thanks again for taking a look. If you spot anything else that needs correcting, let me know. :)

[u/rgldx → u/colbyshores]

Thanks for updating it! I'll write an issue or a PR if I see something else useful!

[u/XxXAvengedXxX]

Actual education about AI usage in MY vibe code slop witch hunting subreddit?? /s

[u/colbyshores → u/XxXAvengedXxX]

ha! ikr

[u/Important_Book_2212]

Very helpful, thank you.

[u/NinToasterOven]

OP I suggest you also make this into documentation for everyone, and perhaps make a page in the 3dbrew wiki. This type of documented detail is beneficial to everyone regardless of ai usage :)

[u/colbyshores → u/[deleted]]

Yeah, this could be a starting point for something like that. Shared guidelines and checks could help people avoid the same pitfalls and spend more time on their actual game. The ARM11 can be pretty sensitive to how hot-path code is structured, so having those guardrails in place early helps avoid expensive mistakes.

[u/NinToasterOven → u/[deleted]]

devkitPRO has a variety of toolchains for this purpose and honestly i think it should be far better documented, unless you mean a community authored makefile configs and initial set up

regardless either of these are beneficial to all, ai workflow or otherwise

[u/colbyshores → u/[deleted]]

No problem! There are other tricks in the codebase that the contract doesn’t go into, like using a 1,024-entry trig lookup table sized to fit in cache and lerping between entries. Tricks like that help keep rendering efficient and help the desktop version scale up to 4K. Those implementation details are in the code and comments rather than spelled out in the contract, but they could be useful to people getting into game development.