// Dora SSR coding rules for game/workspace projects; prevents browser DOM/Canvas/Node.js code in Dora engine scripts and forces Dora API lookup before using unfamiliar engine APIs.
| name | dora-engine-coding |
| description | Dora SSR coding rules for game/workspace projects; prevents browser DOM/Canvas/Node.js code in Dora engine scripts and forces Dora API lookup before using unfamiliar engine APIs. |
| always | true |
These rules apply whenever writing, fixing or reviewing code for a Dora SSR workspace/game project.
init.ts or init.lua..ts/.tsx source files. Do not hand-edit generated .lua unless the task is specifically about Lua output or the project is Lua-only.index.html, DOM Canvas code, etc.) and also has init.ts, treat init.ts as the Dora runtime entry unless the user explicitly asks for a browser/Web IDE frontend.Before writing code, decide the target:
For Dora runtime scripts, never generate:
document, window, HTMLElement, HTMLCanvasElement, CanvasRenderingContext2DrequestAnimationFrame, browser alert, DOM event listenerssetInterval, setTimeout, NodeJS.Timeoutfs/path/processindex.html as the runtime game entryIf those APIs already exist in a Dora runtime project, treat them as incompatible code to rewrite.
Dora has its own TypeScript definitions such as Dora.d.ts. Do not invent names/signatures.
Call search_dora_api before using any Dora API that is not shown in the baseline section below or not already used correctly in the project.
Use:
programmingLanguage: "ts" for .ts files.programmingLanguage: "tsx" for DoraX/JSX files.docSource: "api" for signatures/types.docSource: "tutorial" for usage examples when signatures alone are not enough.docLanguage: "zh" if the user is Chinese or Chinese docs are preferred; otherwise "en".After searching:
.d.ts/tutorial file.Search especially for:
PhysicsWorld, Body, BodyDef, FixtureDef, SensorEntity, Group, Observer, component queriesButton, Menu, AlignNode, UI controlsAudio, AudioSource, buses/effectsthread, threadLoop, sleep, once, loop, scheduler jobsDirector, Camera, Director.ui, Director.entry, scheduler APIsContent, Cache, Path, asset loading/savingSprite, Model, Playable, Action, Move, Scale, Sequence, animation slotsParticle, EffekNode, VideoNode, TIC80NodeTileNodePlatformer, PlatformWorld, platformer bodies/unitsDrawNode, VGNode, nvgMouse, touch, controller, IME, node slotsExample tool searches:
search_dora_api pattern="PhysicsWorld|Body|FixtureDef" docSource="api" programmingLanguage="ts" limit=8
search_dora_api pattern="Button|Menu|AlignNode" docSource="api" programmingLanguage="ts" limit=8
search_dora_api pattern="AudioSource|Audio" docSource="api" programmingLanguage="ts" limit=8
search_dora_api pattern="thread|sleep|threadLoop" docSource="api" programmingLanguage="ts" limit=8
Use Dora runtime modules, not browser packages:
import { ... } from 'Dora';import { React, toNode } from 'DoraX'; and use .tsx.import * as Platformer from 'Platformer'; or exact exports found by API search.import * as ImGui from 'ImGui'; plus enum exports from ImGui when needed.import * as nvg from 'nvg'; when using VGNode/NanoVG APIs.For a tiny runtime prototype, this baseline is allowed without extra API search:
// @preview-file on clear
import { Color, Director, DrawNode, KeyName, Keyboard, Label, Node, Vec2, View } from 'Dora';
const root = Node();
root.addTo(Director.entry);
const draw = DrawNode();
draw.addTo(root);
const title = Label('sarasa-mono-sc-regular', 20);
if (title) {
title.text = 'Dora Game';
title.y = View.size.height / 2 - 40;
title.addTo(root);
}
let x = 0;
root.schedule((dt) => {
if (Keyboard.isKeyPressed(KeyName.Left)) x -= 240 * dt;
if (Keyboard.isKeyPressed(KeyName.Right)) x += 240 * dt;
draw.clear();
draw.drawDot(Vec2(x, 0), 20, Color(80, 180, 255, 255));
return false; // keep scheduling
});
Baseline mapping:
Director.entry, not HTML body/canvas.Node.schedule((dt) => false) or node.onUpdate, not requestAnimationFrame.dt in scheduled updates, not setInterval/setTimeout.DrawNode.drawDot, drawSegment, drawPolygon.Label('sarasa-mono-sc-regular', size) and guard because Label(...) may return undefined.Keyboard.isKeyPressed(KeyName.Left).Keyboard.isKeyDown(...) / Keyboard.isKeyUp(...).View.size.width, View.size.height.Director.entry without extra transforms, the visible world is commonly centered around (0, 0), so screen bounds are often ±View.size.width / 2, ±View.size.height / 2. For child nodes or cameras, compute in that node/camera coordinate space instead of assuming DOM top-left coordinates.Use this as a decision map. It is not a full API reference; exact signatures come from search_dora_api.
| Need | Likely start | Lookup rule |
|---|---|---|
| Basic scene/game loop | Director.entry, Node.schedule | Baseline enough for tiny prototypes |
| Primitive drawing | DrawNode, Vec2, Color | Search for advanced vertices/VGNode |
| Sprites/assets | Sprite, Content, Cache, Path | Search before loading assets |
| Text/UI/layout | Label, Menu, Button, AlignNode, DoraX | Search before UI controls/layout |
| Keyboard/mouse/touch/controller | Keyboard, KeyName, Mouse, node slots | Search beyond simple keyboard |
| Actions/animation | Action, Move, Scale, Sequence, Playable, Model | Search exact signatures |
| Physics/collision | PhysicsWorld, Body, BodyDef, FixtureDef, Sensor | Always search first |
| ECS/game architecture | Entity, Group, components | Always search first |
| Audio | Audio, AudioSource | Always search first |
| Async/coroutines | thread, threadLoop, sleep, once, loop | Search when using coroutine/timing APIs |
| Tile maps | TileNode | Always search first |
| Particles/effects/video | Particle, EffekNode, VideoNode, TIC80Node | Always search first |
| Platformer framework | Platformer, PlatformWorld | Always search first |
init.ts, init.lua, or an existing run script).init.ts uses them.init.ts first; refactor into modules only when it is already running or the user asks.build on the changed file/project when available.success field. Inspect per-file messages; if any message reports failure or diagnostics, fix them before finishing.Dora, DoraX, Platformer, ImGui, nvg) as appropriate.search_dora_api or existing correct project code.dt.Director.entry or an existing Dora node.KeyName enums.Use this skill when designing, creating, or polishing UI/screens/HUDs/menus so the result is visually refined, coherent, responsive, and implemented with the correct Dora UI APIs.
Agent memory files with grep-based scoped recall.
Guide the agent to create a new project skill with correct placement, required metadata, and a practical SKILL.md template.