Gondwana

View saved version →

---
name: create-gondwana-game
description: Builds or extends games, demos, samples, and gameplay features with the Gondwana C#/.NET game engine. Use when the user asks to make, create, scaffold, implement, port, or add a game or game mechanic with Gondwana, including requests such as "make Pong with Gondwana", "create a platformer", or "add particles/collisions/input to my Gondwana game".
---

# Create a Gondwana Game

Use this skill for game-facing implementation with Gondwana.

The goal is not merely to produce plausible C# game code. Produce code that matches the **current Gondwana public API and intended architecture**.

## Establish authoritative context

Before substantial implementation:

1. If the Gondwana MCP tools are available, call `get_repository_info`.
2. Read `AGENTS.md` from the current public/default Gondwana source unless the user explicitly names another ref.
3. Read `docs/ai/README.md`.
4. Inspect `Tooling/Gondwana.Templates/` for current project/startup conventions.
5. Identify and inspect the closest current demo in `Demos/`.
6. Search/read the source for the public types the implementation will use.
7. Search/read the relevant wiki pages for the intended mental model.

Do not invent an API because a similarly named method would be conventional in another game engine.

If live Gondwana repository access is unavailable, say that exact API verification is unavailable before relying on uncertain signatures.

## Choose the closest existing path

Prefer the nearest working Gondwana example:

- Windows/WinForms game startup: inspect the current WinForms template and Windows demos.
- Avalonia desktop: inspect current Avalonia hosting/examples.
- Blazor/WebAssembly: inspect the current Blazor hosting/examples.
- Platforming/collision gameplay: inspect `Demos/Gondwana.Platformer/`.
- Ship movement/rotation/combat/HUD patterns: inspect `Demos/Gondwana.SpaceDuel/`.
- Particles: inspect `Demos/Gondwana.ParticleTest/`.
- Coordinate systems/projections: inspect `Demos/Gondwana.CoordinateTest/`.
- Small game structure: inspect current compact demos such as `Demos/Gondwana.Flappy/`.
- Widgets: inspect `Gondwana.Widgets/` and `Demos/WidgetsTest/`.

Do not copy a stale demo pattern without checking the engine API it calls.

## Implementation rules

- Use public Gondwana APIs in game code.
- Keep game-specific behavior in the game project.
- Add core-engine behavior only when the requested capability genuinely belongs in Gondwana.
- Preserve the code-first model; do not introduce an editor-owned workflow.
- Respect package boundaries between core, hosting, widgets, adapters, optional packages, tooling, and demos.
- Treat world, layer/grid, and screen coordinates as distinct spaces.
- Account for the intentionally different bitmap and GPU rendering paths when rendering/invalidation is relevant.
- Prefer straightforward sample code over abstraction created only to reduce a few repeated lines.

When the request reveals a missing engine capability, separate the proposed engine change from the game/demo code so the user can evaluate the architectural addition explicitly.

## Deliverables

For implementation requests, provide the smallest useful artifact that matches the user's workflow:

- focused code snippets for small changes,
- complete files for small self-contained examples,
- an apply-ready patch when modifying an existing repository,
- project boilerplate when creating a new game.

Include tests when changing reusable engine behavior. Demo-only gameplay does not need to become a core test unless it exposes a reusable regression.

## Verification

Before claiming an implementation is correct:

1. verify the exact public types/members used,
2. check relevant tests,
3. check the closest demo/template,
4. account for lifecycle/ownership implications,
5. build/test when the environment permits it.

If verification cannot be performed, state what remains unverified rather than presenting guessed API usage as current Gondwana code.

Referenced files: 1

View saved version →

---
name: debug-gondwana-game
description: Diagnoses and fixes Gondwana game, integration, and engine behavior using current source, tests, demos, and documentation. Use when the user reports a bug, failing test, rendering/input/collision/movement issue, unexpected lifecycle behavior, compilation problem, regression, or asks why Gondwana code is not behaving as expected.
---

# Debug a Gondwana Game

Use this skill to diagnose Gondwana behavior before proposing a fix.

The central question is: **which layer actually owns the problem?**

## Establish current behavior

For a nontrivial problem:

1. If the Gondwana MCP tools are available, call `get_repository_info`.
2. Read `AGENTS.md` and `docs/ai/README.md`.
3. Inspect the source named by the user or implicated by the symptom.
4. Follow direct collaborators and lifecycle/ownership relationships.
5. Search `Testing/Gondwana.Tests/` for the affected type or behavior.
6. Inspect the closest current demo when the symptom is game-facing.
7. Consult the relevant wiki page after understanding current code.

Treat current source and tests as authoritative for current behavior. Use the wiki to understand intended design.

## Classify the problem

Explicitly determine whether the defect is primarily in:

- the user's game code,
- demo/sample code,
- a public Gondwana API,
- engine internals,
- a platform adapter,
- hosting/lifecycle integration,
- widgets/input routing,
- tooling/assets,
- documentation that has drifted from current code.

Do not change engine internals merely to make incorrect game usage appear to work.

## Trace the relevant implications

Investigate only the cross-cutting areas that matter to the symptom, including:

- initialization and attachment order,
- engine-cycle versus frame-render timing,
- event ordering,
- world/layer/grid/screen coordinate conversion,
- camera/view/viewport ownership,
- dirty-region invalidation,
- GPU full-viewport rendering,
- collider registration and collision profile/mask resolution,
- animation/frame-derived state,
- serialization/deserialization,
- caching/copying,
- input polling, widget focus/capture, and hit testing,
- dispatcher/thread affinity,
- native/platform presentation,
- disposal and resource ownership.

Do not shotgun-edit all of these. Use the checklist to avoid missing a relevant coupling.

## Fix discipline

Prefer the smallest fix that restores the intended contract.

- Preserve public behavior unless the task intentionally changes it.
- Keep platform-specific fixes in the appropriate adapter/hosting package.
- Do not force bitmap and GPU paths into artificial symmetry.
- Avoid unrelated cleanup while fixing a regression.
- Add a focused regression test when engine behavior changes.
- Preserve an existing test unless the requested contract intentionally supersedes it.
- If the documentation is stale but code/tests are correct, fix or flag the documentation rather than regressing the implementation.

## Explain the diagnosis

When reporting a fix, distinguish:

1. **Observed behavior**
2. **Root cause**
3. **Why the proposed change belongs in this layer**
4. **Other implications checked**
5. **Regression coverage**
6. **Anything still unverified**

For a patch request, generate an apply-ready focused patch instead of a prose-only list of edits.

Referenced files: 1

View saved version →

---
name: explain-gondwana-api
description: Explains Gondwana APIs, architecture, concepts, and current engine behavior using the official wiki plus live source and tests. Use when the user asks how Gondwana works, what a type/property/subsystem does, why the engine is designed a certain way, how two Gondwana concepts differ, or whether a documented capability exists today.
---

# Explain a Gondwana API or Concept

Use this skill for accurate explanations of Gondwana rather than implementation-first work.

## Use the right source for the question

Gondwana deliberately has different sources of truth for different questions.

Use the **wiki** first for:

- mental models,
- terminology,
- architecture,
- normal game-developer workflows,
- coordinate-space explanations,
- subsystem overviews.

Use **current source and tests** to verify:

- exact APIs and signatures,
- current implementation order,
- ownership,
- inheritance/copy/cache behavior,
- current regression guarantees,
- whether a feature actually exists on the current branch.

Use demos/templates to show how current public APIs are composed in real game code.

Do not treat `ROADMAP.md`, an open issue, old changelog text, or historical documentation as proof that a feature is implemented.

## Workflow

1. If the Gondwana MCP tools are available, call `get_repository_info` for source-sensitive questions.
2. Read/search the relevant wiki topic.
3. Search/read the defining source files for exact implementation claims.
4. Search relevant tests when behavior or ordering matters.
5. Inspect a current demo/template when a usage example would improve the answer.
6. Reconcile the sources using the precedence in `AGENTS.md`.

If documentation and current implementation disagree, say so plainly and identify which describes current behavior.

## Answer style

Start with the conceptual answer, then add implementation detail only as needed.

For code-facing explanations:

- name the relevant Gondwana types,
- distinguish public API from internals,
- identify coordinate space when relevant,
- identify lifecycle/update/render stage when relevant,
- cite or name the relevant source paths and wiki pages when the host supports citations.

Avoid explaining Gondwana by analogy to Unity, Godot, ECS engines, or generic game-engine conventions when Gondwana's own architecture answers the question directly.

## Roadmap versus current behavior

When a question concerns planned work, label it clearly:

- **Implemented now**
- **Partially implemented**
- **Planned**
- **Exploratory/design discussion**

Never silently upgrade planned behavior into a current guarantee.

Referenced files: 1