Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (65 loc) · 3.9 KB

AGENTS.md

File metadata and controls

80 lines (65 loc) · 3.9 KB
Raw

AGENTS.md — guidance for AI coding agents

This repository is a template for building third-party plugins for Phaser Editor v5. If you are an AI assistant helping someone extend their plugin, read this first, then read the focused docs under docs/.

What this project is

  • A Phaser Editor plugin is a folder with a plugin.json manifest plus the JavaScript/CSS it lists. There is no webpack and no runtime npm.
  • Source is TypeScript compiled with tsc and outFile into a single concatenated file (<plugin>/_out/<id>.js). Each plugin is one TS project.
  • The editor API is consumed through bundled declaration snapshots in types/ — one .d.ts per editor plugin (colibri.d.ts, phasereditor2d.files.d.ts, phasereditor2d.phaser.d.ts, and the rest), so the full editor API is available. You do not have the editor source — treat these .d.ts files as the API source of truth and grep them instead of guessing at API shapes. They are refreshed with npm run update-types (needs PHASEREDITOR5_HOME).
  • Code is organized with TypeScript namespaces (e.g. myplugin.example), not ES modules. Files in a plugin share one namespace and are merged by the compiler; do not add import/export statements between plugin files.

The example to copy from

myplugin.example/ is a complete, working plugin. It is the best reference for patterns — when adding something new, find the closest existing piece and copy its structure:

  • src/ExamplePlugin.ts — the colibri.Plugin subclass; everything is registered in registerExtensions(reg) via reg.addExtension(...).
  • src/editors/TodoModel.ts — a data model + content-type id.
  • src/editors/TodoEditor.ts — a custom HTML-based FileEditor with commands, a toolbar, and selection wiring.
  • src/editors/TodoEditorOutlineProvider.ts — feeds the Outline view.
  • src/editors/TodoEditorProperties.ts — Inspector property sections.
  • src/editors/NewTodoFileExtension.ts — a New File wizard entry.

How to add a feature (workflow)

  1. Pick the extension point. See the catalog in docs/extension-points.md. Almost every feature is a subclass of colibri.Extension registered in registerExtensions.
  2. Read the matching recipe in docs/recipes/ and the referenced example file.
  3. Confirm the API by grepping types/colibri.d.ts (or types/phasereditor2d.files.d.ts) for the classes/methods you use.
  4. Write the code in a new file inside the plugin's src/ (same namespace), and register it in ExamplePlugin.ts.
  5. Build with npm run build (or npm run watch) and fix any type errors before finishing.

Conventions

  • IDs are namespaced: "<pluginId>.<Name>" (e.g. myplugin.example.AddTask). Keep command/category/content-type ids unique and prefixed with the plugin id.
  • Register CSS by adding the path to the styles array in plugin.json.
  • Theme-correct UI: separate layout (theme-agnostic) from color (scoped per theme class: .dark .X, .light .X, …). Never hardcode a single color. See docs/recipes/add-styles.md.
  • Prefer existing controls (colibri.ui.controls) over hand-built DOM when possible — they inherit theming for free.

Build / verify

npm install      # once
npm run build    # compile all plugins (tsc -b)
npm run watch    # rebuild on change while developing

A change is not done until npm run build succeeds with no type errors.

Don't

  • Don't introduce a bundler, ES module import/export, or runtime npm deps.
  • Don't edit files under types/ to make code compile — those are API snapshots. Update them only to track a new editor version (see docs/architecture.md).
  • Don't invent API: if it isn't in the .d.ts, it isn't available.