1. Zero Allocation on Hot Paths:
   • Must reuse slices (

     slice = slice[:0]

     ) and object pools (

     sync.Pool

     or generic Pool) in the

     Update()

     and

     Draw()

     loops to ensure zero GC pressure per frame.
2. Main Thread Binding:
   • All drawing logic (

     DrawImage

     ,

     NewImage

     ) must be strictly restricted to the

     Game.Draw()

     main callback to ensure execution on the OS main thread.
3. Concurrency Safety:
   • When handling AI or physics calculations in Goroutines, results must be passed back to the main loop via

     Channel

     , or shared states must be locked with

     sync.RWMutex

     .
4. Manual VRAM Disposal:
   • Any dynamically created

     ebiten.Image

     (non-embedded resources) must explicitly call

     .Dispose()

     after use; do not rely on GC.

1. 🚫 Forbid Object Creation in Loops:
   • Strictly prohibit using

     fmt.Sprintf

     (implicit interface conversion),

     make([]int)

     or

     &Vector{}

     in

     Update

     .
2. 🚫 Forbid Cross-Thread Rendering:
   • Never call any graphics API in a self-started

     go func()

     . This will cause random crashes or

     invalid memory address

     errors.
3. 🚫 Forbid Concurrent Map Reads/Writes:
   • Strictly prohibit accessing the same

     map

     from multiple Goroutines without locking. Go's Map race detector will directly panic the entire process.
4. 🚫 Forbid Frequent CGO Interactions:
   • Avoid high-frequency calls to tiny C functions (such as Raylib's single-point drawing) in the

     Update

     loop. Data must be batched on the Go side and passed to the C side in one go.

Never stuff all code into

main.go

. Follow the Go standard project layout.

• Directory Structure:

  • cmd/game/main.go

    : Program entry point, only responsible for initializing the window and starting the Game Loop.

  • internal/game/

    : Core logic, invisible to external parties.

  • internal/assets/

    : Interface for embedded file system (

    embed.FS

    ).

  • internal/ecs/

    : (Optional) Stores Component and System definitions.
• Actions:

  1. go mod init <module>

  2. Create

     internal/game/game.go

     and define the

     Game

     struct.
  3. Call

     ebiten.RunGame(&game.Game{})

     in

     cmd/game/main.go

     .

A game is not a single big loop, but a series of scene switches (Logo -> Menu -> Play -> Over).

• Pattern:
  • Define the

    Scene

    interface: Must include

    Update() error

    and

    Draw(screen *ebiten.Image)

    .
  • Hold

    currentScene Scene

    in the

    Game

    struct.
• Actions:
  1. Implement

     SceneManager

     and provide the

     SwitchTo(Scene)

     method.
  2. Ensure

     Game.Update()

     is just a proxy:

     return g.currentScene.Update()

     .
  3. Implement the first

     TitleScene

     and mount it.

As the number of entities increases, OOP inheritance trees become performance bottlenecks.

• Strategies:
  • Small number of entities (<500): Use Composition Pattern. Define the

    GameObject

    struct, embedding

    *Sprite

    and

    *Position

    .
  • Large number of entities (>1000): Must use ECS (Entity Component System). Recommended libraries are

    donburi

    or

    arche

    .
• Actions:
  1. Define

     Component

     interfaces or struct data.
  2. Implement

     System

     (such as

     MovementSystem

     ), only iterating over entities with the

     Velocity

     component.

Don't directly write

ebiten.IsKeyPressed(ebiten.KeySpace)

in logic code.

• Input Mapping:
  • Create

    InputSystem

    to map physical keys (Space, A, GamepadA) to logical intents (

    ActionJump

    ,

    ActionShoot

    ).
  • The logic layer only checks

    input.IsActionJustPressed(ActionJump)

    .
• Resource Pooling:
  • Establish a global (or scene-level)

    AssetLoader

    .
  • Use

    sync.Map

    or ordinary

    map

    to cache loaded images to avoid repeated I/O.

Working locally doesn't mean it can be distributed to players.

• Actions:
  1. Configure

     .air.toml

     to implement code hot reloading (support for graphical windows is limited, but useful for logic debugging).
  2. Write

     Makefile

     or

     scripts/build.py

     to formalize build parameters:
     • Windows:

       GOOS=windows GOARCH=amd64 go build -ldflags="-H windowsgui -s -w"

     • Web:

       GOOS=js GOARCH=wasm go build -o game.wasm

• References:

  • references/ebitengine_patterns.md

    : Ebitengine in-depth design patterns, performance pitfalls, and optimization suggestions.

  • references/vfx_guide.md

    : Visual Effects Guide (Screen Shake, Shaders, Particles).

  • references/publishing.md

    : Official release rules, compilation parameters, and review guidelines for Steam, Itch.io, and mobile app stores.

  • references/genre_cardgame.md

    : Engineering Guide for Card Games (Hand algorithms, data structures, state machines).

  • references/genre_simulation.md

    : General Architecture for Simulation Games (Block grids, resource flow diagrams, deterministic ticks).
• Scripts:

  • scripts/build_all.py

    : One-click cross-platform cross-compilation automation tool (supports Wasm, Windows, Linux, macOS).