sgdk-math

SGDK Math

Choose the coordinate range, smallest useful fraction and largest intermediate before choosing a type. A wider storage type does not automatically mean a more accurate or safer multiply/divide implementation.

Choose the right reference

• Numbers and arithmetic: SGDK's actual formats,

conversions, rounding, overflow and multiply/divide limits.

• Motion and effects: degrees, vectors, aiming,

diagonal movement, squared distances, interpolation and bounded tables.

• Math Lab: a runnable perspective starfield and

orbit/figure-eight/spiral formations, with controls and a playtest checklist.

Use ewrogers/sgdk:latest and check its inc/maths.h, inc/types.h and src/maths.c before using an unfamiliar helper. These references were checked against SGDK 2.11. In particular, current F16_sin/F16_cos take degrees; deprecated sinFix16 uses a different angle convention.

Make the calculation safe

Keep world positions separate from screen coordinates. Prefer fix32 or integer world positions when a level exceeds fix16's range. Use small fix16 offsets and velocities where they fit. Convert at explicit boundaries; do not cast between fixed-point formats as though their scales were identical.

Widen before subtracting or multiplying. Establish a valid divisor and bound the quotient before division. Avoid signed overflow, shifting negative signed values in your own C and assuming that a wrapped result will be useful. SGDK's helpers have implementation-specific limits too; follow the reference rather than replacing them with floating point or an untested fast-math trick.

For a new effect, test known points, negative inputs, near-zero divisors, maximum supported coordinates and a full angle cycle. Compare with an independent higher-precision oracle within a stated tolerance. Execute the actual target SDK routines when host arithmetic cannot establish their behavior.

Keep repeated work small

Cache a shared sine or reciprocal table when the memory tradeoff is worthwhile. Bound the angle/depth index before looking it up. Prefer squared-distance tests to square roots when only a threshold matters. Do not replace an exact hit test with SGDK's approximate distance without allowing for its error.

Use a consistent simulation clock and cache input once per display frame. Separate simulation coordinates from rendering so a PAL display or a missed frame does not silently change the units of velocity. Measure optimized ROMs; a successful build or smooth host animation does not establish a 68000 budget.