quest'n'click 4.5.0 · r1

Built for quest'n'click 4.5.0, revision r1. Whether it is published, and which one is current, is recorded at publication.json.

Welcome

Français · Type: explanation · Audience: contributor · Context: engine repository · Status: ready · Applies from: 4.4.0

quest'n'click is a small project with one maintainer, @wanoo. A contribution is welcome when it is small, tested and explained: a bug fix with its regression test, a missing case of the validator, a clearer page. This page says why the project works the way it does; the pages it links say how.

Why the project works this way

A game is data, never code. The engine in src/engine/ reads a game folder games/<id>/ and knows nothing else about it. That is what lets the validator, the solver, the replay, the Studio and an AI assistant all read and check the same content. A change to the engine keeps that promise: gameplay stays declarative in games/<id>/, and geometry stays in layout/*.json (see Architecture).

Most mechanics already exist. Before asking for a new command or field, read the classic mechanics of the genre (Classic mechanics, the old docs/en/CLASSICS.md): insult fights, melting items, patrols, haggling and cross-character puzzles are combinations of rules, flags, scripts and events the engine already has. A request for something new starts from the feature issue template, after that page.

Every claim has a check. The project prefers a gate that fails to a promise that drifts. Coverage floors only rise (The coverage ratchet), the engine's behaviour is frozen in a baseline (The quality baseline), and every surviving mutant is named with its reason (Mutation testing). What only people and real devices can check is a field pass, reported in each release (Field passes).

What is public is a promise; the rest may move. The public DSL, the save envelope and the plugin contracts follow semantic versioning from v3 on, except on the 4.1.8–4.1.15 incubation line, where a break was documented with a migration (Stability and support). Internal modules are not compatibility promises unless a page says otherwise (Import boundaries).

How a contribution goes

  1. Prepare the machine once: Developer setup.
  2. Read the code with Architecture, then walk the Code tour (half an hour).
  3. Change one thing, with the loop of The dev loop. Keep it small; a bug fix comes with the test that would have caught it.
  4. Name the branch, the pull request and the fragment of the CHANGELOG as Conventions says.
  5. Run the checks of Before a pull request, open the pull request from the template, and read what CI says (CI explained).

Working with an AI assistant is expected and has its own rules: Contributing with AI agents.

Limit · private-assets Never add private source assets, or material whose commercial rights are unclear. Every asset of the sample game is CC BY 4.0 (Licences and credits).

Conduct and security

Everyone here follows the Code of conduct. A vulnerability is reported privately, never in a public issue: Security policy. How decisions are made, and who makes them, is in Governance and Decisions and ADRs.

Decisions and ADRs

Edit the source of this page · Report an error