planetis-m

Game System Design Protocol for AI Agents (Nim)

Directive

When asked to architect, implement, or review a game system in Nim, follow this protocol sequentially. Do not skip steps. Do not introduce abstractions not prescribed here unless the user explicitly requests them.

---

Phase 1: Classify the Subsystem

planetis-m

Architecting Games in Nim: A Pragmatic Guide

1. The Core Recommendation

Start simple. Stay simple. Most games never need ECS.

The game we just built — a survival arena with hundreds of agents, projectiles, particles, spatial queries, and camera-following — runs in a fraction of a millisecond using nothing more exotic than seq[Agent] and seq[Color]. The entire architecture is plain Nim: types, arrays, and procs. There is no framework, no query layer, no entity manager, no component registration, no archetype migration.

This is not a compromise. It is the optimal answer for the vast majority of games.

planetis-m

Results are stable across 3 runs. The pattern holds:

System	ECS-Arch	MI-AoS	Consistency
ai_update	~2.13	~1.71-2.93	Noisy — genuine tie (data fits L2)
move	~0.76	~1.19	Stable — Arch wins 1.6x
combat	~0.27	~0.45	Stable — Arch wins 1.6x
projectile	~1.12	~0.74	Stable — AoS wins 1.5x
cull	~2.8	~0.55	Rock solid — AoS wins 5x
despawn	~0.002	~0.001	Stable — AoS wins 2x

planetis-m

## Archetype ECS vs MI-AoS Benchmark
## ==================================
## Two approaches for a mixin-based entity simulation with cross-entity refs:
##
##   1. ECS-Archetype — SoA columns within archetype buckets, no signature scan
##   2. MI-AoS        — per-archetype value arrays (composition), direct field access
##
## Scenario: Tactical field simulation
##   Building   {pos, sprite}                        — static, can be a parent
##   Unit       {pos, worldPos, vel, hp, sprite,

planetis-m

## MI vs ECS Benchmark v3 — Grouped SoA + Archetype ECS
## ====================================================
## Addresses v2 feedback: fragmented single-field columns waste cache.
##
## Four approaches:
##   1. ECS-Frag       — 8 separate SoA columns (baseline, from v2)
##   2. ECS-Grouped    — 5 grouped columns based on system access patterns
##   3. ECS-Archetype  — archetype buckets with DenseVec columns (from paste)
##   4. MI-AoS         — per-archetype value arrays (baseline winner)
##

planetis-m

## MI vs ECS Benchmark v2 — Cross-Entity References
## ==================================================
## Real-world complexity: entities reference each other (targeting,
## parent hierarchy), dynamic spawn/despawn of projectiles.
##
## Three approaches:
##   ECS     — SoA columns, flat entity indices as references, signature scan
##   MI-AoS  — per-archetype value arrays, typed indices as references
##   MI-Ref  — per-archetype heap ref objects, pointers as references
##

planetis-m

## MI vs ECS Benchmark
## ===================
## Compares three approaches for a mixin-based entity simulation:
##
## 1. ECS-SoA    — type-erased columns, signature queries (adapted from paste)
## 2. MI-AoS     — composition, per-archetype value arrays, direct field access
## 3. MI-vtable  — role interfaces with per-type vtables, virtual dispatch
##
## Scenario: Swarm simulation with 3 archetypes (mixin composition):
##   Decoration: {pos, render}           — static visual element

planetis-m

## Extended validation: diamond inheritance + heterogeneous polymorphism

# ============================================================
# Shared base (top of diamond)
# ============================================================

type
  Positioned = ref object of RootObj
    x, y: int

planetis-m

You are a deterministic game engine simulating the board game Diplomacy.

Your role:

• Act as the game master, world simulator, and all non-player countries.
• I am the player controlling one country.
• You must strictly follow official Diplomacy rules (movement, support, convoys, supply centers, builds).
• No randomness. All outcomes must be logically derived from orders.

Game setup:

• Standard Diplomacy map (1901 start).

planetis-m

---

name: nim-error-handling description: Design clear Nim error-handling flows. Use when reviewing failure behavior, exception boundaries, or batch processing.

Nim Error Handling

Use this skill when deciding where code should raise, catch, translate, retry, or return structured failure data.

Rules