Files
aego/engine/docs
sanspie 50be5c04bc
ci-platforms / darwin amd64 smoke (push) Skipped
GitHub / linux amd64 native GitHub-hosted native CI: success
ci-platforms / windows amd64 smoke (push) Skipped
GitHub / windows amd64 native GitHub-hosted native CI: success
GitHub / darwin arm64 native GitHub-hosted native CI: success
GitHub / darwin amd64 native GitHub-hosted native CI: success
ci / checks (push) Failing after 1h21m34s
ci / native-authoring (push) Skipped
ci-platforms / darwin arm64 smoke (push) Skipped
github-native / gitea-pending (push) Skipped
github-native / darwin amd64 native (push) Skipped
github-native / linux amd64 native (push) Skipped
github-native / windows amd64 native (push) Skipped
github-native / darwin arm64 native (push) Skipped
github-native / gitea-result (push) Skipped
ci / build (amd64, linux, ubuntu-24.04) (push) Successful in 12m4s
ci / release (push) Skipped
Stage 12.5: Art Workspace and asset authoring
Add dockable Art tools, animation and previews, guarded asset workflows,
and the Web Asset Studio built on the shared Art Core. Expand English and
Russian documentation, interactive Try scenes, examples and editor icons.

Add audio waveform navigation, source analysis, guarded previews and a
browser Worker mixer. Preserve source changes and recovery with bounded
checks, and strengthen native, browser and interoperability CI.

Prepare version 0.12.5 and manually built native artifact candidates.
Fix the production site image demo build dependency.
Reuse immutable scene indices when capturing keyframes.
Wait for real Persist save/load completion in component tests.
Stabilize browser Game View captures outside pointer hover.
Aseprite interchange and persistent Audio EDL recovery remain limited;
the artifact workflow does not publish releases or change stable.
2026-11-15 10:37:50 +03:00
..

Documenting a module

The documentation site, the editor's documentation panel, hover text in the script editor and docs_search over MCP all read one registry, assembled from the engine and from every module. This page lists what a module provides and what aego docs check --strict holds it to. The writing rules are in docs/style.md, the terms in docs/glossary.md; the decision is D347 in ARCHITECTURE.md.

What a module provides

  • Descriptions in Go. schema.Doc on every component, schema.FieldDoc on every field the Inspector shows, bind.Doc on every script function, method and signal. A field without a description is an error even without --strict.
  • Pages. Markdown files under res/docs, embedded and passed to Registry.Docs. Each file starts with a front matter block and may hold several pages separated by --- blocks.
  • Try scenes. res/docs/try/<Component>.aescene, with <Component>.aes for its script and <Component>.<name>.aeprefab for prefabs. The component page runs it in the browser.
  • Diagnostics. res/docs/diagnostics/<CODE>.md for every code the module declares in Info.Codes, with an example scene that reproduces it.
  • Messages. res/i18n/en.aetext and its translations, passed to Registry.Messages, with keys under i18n.<module>.. go run ./tools/i18n extract writes the English catalog from the Tr calls.

Front matter

Key Meaning
id Unique page id, used by ref: links. Required.
title Title in the navigation and on the page.
parent Id of the page this one sits under.
group, group_title, group_icon, group_order The navigation group, or a new one.
order Place among siblings.
icon An editor atlas icon, such as cat.gameplay.
summary One sentence for lists and search, at most 160 characters. Without it the first sentence of the opening paragraph is used.
try, try_select A try scene for a guide page and the node it selects.
keys Keywords whose hover text this page provides.
search_names Search-only aliases, for example [bloom, glow]. Translated files can add local phrases; aliases work in both languages without changing script keyword hover keys.
params Documentation-only names for every parameter of an existing function or method, for example [key, value]. Count and names are validated; bindings and ABI are unchanged.
style_allow Lint patterns this page may match, such as [agent]. Say why in the review.
editor_only The page is shown only in the editor.
code, severity, scope, example Diagnostic pages only.

Writing

  • Describe what the reader sees and does. Implementation details go to ARCHITECTURE.md.
  • A description starts with the verb: "Pushes the body…", not "ApplyForce pushes the body…". The site removes a leading name, so Go comments may keep Go style.
  • Give units and what 0 or -1 means: "Seconds of game time before the node comes back", "0 never snaps".
  • One fact per sentence, at most four sentences per paragraph. A bold phrase that opens a paragraph is a heading; use a heading.
  • Name things as the editor does: Rigid Body 2D in prose, physics.Body2D in code. Use the terms in docs/glossary.md.
  • Every page opens with one or two sentences on what it covers, before the first heading.
  • A diagnostic page says in one sentence what happened and in one how to fix it.

Code blocks

Fence Checked
```aes run Compiled and shown with a Run button.
```aes check A whole file, compiled together with the aes check blocks above it on the page; a later version of a script replaces the earlier one.
```aescene check A whole scene, played for 60 frames with those scripts. A load error, a fault, a logged warning, a scene problem or a reference to a missing node fails the check.
```go Formatted with gofmt and built against sdk.
other Shown as is.

[text](ref:<id>) links a page, a component (ref:gameplay.Motion2D), a field or a script function. A broken ref: link is an error. A name in backticks that looks like a component, function or field must exist in the reference.

The website only auto-links exact qualified technical IDs and registered diagnostic codes in prose. It does not guess links for bare names such as Floor, State or Range, or for identifiers inside executable snippets: the syntax highlighter cannot resolve local declarations or shadowing. Add an explicit ref: link in the explanation when a snippet uses an API. Code copying preserves the original source.

Checking

aego docs check --strict   # every rule, as CI runs it
aego docs report           # one row per page; a red row has errors
make site-check            # the check above, then the site build tests

The rule codes are DOC010 to DOC023; aego docs check prints each finding with its code, page and line. Prose patterns live in engine/docs/lint.aetext.