sgdk-best-practices

SGDK Best Practices

Make the important contracts visible: ranges, units, ownership, lifetime and failure behavior. Preserve the game's existing architecture and creative direction. These are implementation patterns, not a new engine or style guide.

Treat Labs as optional evidence for a specific technique. Explain the contract being reused and adapt it to the game; do not inherit a Lab's controls, progression, scene flow or module layout merely because working code exists. Whole-game copying is appropriate only when the developer asks for it.

Choose the relevant check

• C correctness: promotions, overflow, shifts,

alignment, aliasing and byte formats across host and target builds.

• Module boundaries: small interfaces, private state,

borrowed resources and partial initialization without a prescribed layout.

• SGDK ownership: sprite cleanup, queued DMA,

foreground/interrupt responsibilities and the selected compiler's defaults.

• Executable examples: checked arithmetic and byte

decoding, transactional sprite acquisition, and a copied palette upload.

Read the reference that fits the change; do not load every specialist manual. The examples build independently. Other installed SGDK skills are optional: sgdk-project owns setup, sgdk-math numeric representations, sgdk-scenes scene transitions, sgdk-performance profiling, and sgdk-debug fault diagnosis. This skill supplies the C and lifetime contracts underneath those workflows.

Apply a contract, then prove it

Before changing code, identify who calls it and what must remain true. Record units and valid ranges where they are not apparent. Distinguish borrowed data from owned resources and choose a useful response to exhaustion or invalid input. Do not silently change gameplay to accommodate a convenient implementation.

Check unfamiliar APIs against the headers and implementation in the selected ewrogers/sgdk:latest container. Pull it before validation and record the actual SDK/compiler versions. The references were checked against SGDK 2.11 and the container's GCC 16.2.0. C17 is the baseline; isolate SDK/GCC extensions at the boundary rather than assuming desktop and target ABIs match.

Keep public headers focused on the operations callers need. Hide internal state; avoid giving unrelated modules writable globals or raw ownership of SDK objects. A simple struct and a few functions may be sufficient. Preserve an established layout unless moving code solves a concrete dependency problem.

Test boundary values, rejected operations, repeated cleanup and recovery after failure. Run the portable parts as optimized host C, then compile the SDK-facing parts with the real SDK. Use target execution for ABI-sensitive behavior. Mocks check your adapter's contract; they cannot establish what SGDK actually does.

Treat C correctness, SDK requirements and optional conventions separately. Do not impose a universal ban on allocation, require hand-written assembly or copy a Lab's art, music, mood, tuning or genre rules into another project.