cocos-creator-gameplay-architecture

Cocos Creator Gameplay Architecture

Overview

Use this skill to build Cocos Creator gameplay that can actually be wired into scenes and prefabs. Treat TypeScript code, component properties, node hierarchy, assets, and runtime lifecycle as one system.

Target Cocos Creator 3.8 unless the project proves another version. Prefer project-local conventions over generic patterns.

Core Workflow

1. Inspect the project before editing.
   • Check assets/, settings/, tsconfig.json, existing scripts, scenes, prefabs, and naming conventions.
   • Identify whether the task needs code only, scene/prefab wiring, assets, or build changes.
   • If there is no project yet and Cocos local MCP tools are available, use cocos_local_create_project with the empty-2d template as the default start for a 2D mini-game; it should also create assets/scenes/Main.scene.
2. Design the runtime flow.
   • Identify game states, UI states, input sources, resource ownership, and reset/restart behavior.
   • Classify complexity before coding: greybox, small vertical slice, or production-oriented slice. Combat, waves, economy, progression, upgrades, affixes, inventory, multiple actor types, and data tables are signals to consider explicit system boundaries.
   • For small or production-oriented slices, sketch a system boundary plan before implementation: candidate domain systems, data/config modules, scene-facing adapters, event flow, ownership, and cross-system dependencies. Keep the plan proportional to the slice.
   • Define a layout contract before implementation: target runtime, target device class, orientation, design resolution, fit policy, safe-area behavior, and the screen regions owned by gameplay and HUD.
   • Define an asset policy for the slice: generated/staged assets through cocos-asset-pipeline-director, existing project assets, or deliberate engine-geometry placeholders. For from-zero mini-games, prefer a minimal generated placeholder pack when the asset MCP is available.
   • For generated gameplay assets, require an asset review handoff before wiring: role, orientation, alpha/silhouette quality, mobile readability, animation readiness, and collision fit. Use cocos-asset-review-director when available.
   • For games where motion carries readability or feel, define an animation/VFX contract before implementation: which actors need sprite sheets, state frames, one-shot effects, loops, and Cocos AnimationClip or frame-sequence playback.
   • For gameplay randomness, define a runtime randomization contract before implementation: which outcomes are random, what data drives them, whether a seed is needed, and what system owns reproducibility and tuning.
   • Keep a small vertical slice playable before adding breadth.
   • For a new mini-game prototype, use cocos_local_create_minigame_skeleton when available to create a baseline GameManager, HUD, input, player controller, pool manager, and starter scene blueprint.
   • For non-trivial games, consider cocos_local_create_architecture_skeleton when available before feature scripts. Use its preset as a starting point to prune, merge, or rename systems according to the actual design, then create thin Cocos Components that host or adapt the chosen systems.
3. Implement Cocos components.
   • Use @ccclass, @property, and Component lifecycle correctly.
   • Expose scene-tunable values with typed @property fields instead of magic constants.
   • If available, use cocos_local_create_component_script to create new TypeScript component files with valid Cocos Creator 3.8 structure.
4. Wire scene dependencies deliberately.
   • Prefer explicit serialized references for authored scene nodes.
   • Use lookup helpers sparingly and fail loudly when required nodes are missing.
   • For generated starter projects, open or reuse the project with cocos_local_open_project, wait with cocos_local_wait_for_editor_bridge, then apply the starter blueprint with cocos_local_apply_scene_blueprint after a scene is active.
   • When switching between local Cocos projects, treat already-open Creator windows and bridge ports as shared environment state. Reuse an existing editor for the same project; close unrelated project windows or use distinct bridge ports when routing could become ambiguous.
5. Verify in runtime context.
   • Run typecheck/build when available.
   • Confirm scene entry, input, state transitions, UI updates, and restart paths.