Generate a fresh standard UUID4 (36-char dashed lowercase hex).

Used as the main UUID for new scripts, scenes, prefabs, and images.

Compress a 36-char UUID to Cocos Creator's 23-char short form.

Required when referencing a custom TS script class as a component __type__ in a scene/prefab JSON. Example: '5372d6f5-721e-43f6-b004-d30da1c8a9a0' -> '5372db1ch5D9rAE0w2hyKmg'

Reverse cocos_compress_uuid: 23-char short -> 36-char dashed.

List every locally installed Cocos Creator version.

Returns a list of {version, exe, template_dir} dicts. Looks under /Applications/Cocos/Creator on macOS, C:/CocosDashboard/Creator on Windows, /opt/Cocos/Creator on Linux.

Initialize a new Cocos Creator project from a template.

Copies a built-in template (default empty-2d) into dst_path, patches package.json with a fresh project UUID and the right creator version, and creates standard assets/ subdirectories.

Use cocos_list_creator_installs first to see available versions.

Read package.json + list assets / scenes / scripts in the project.

List all assets in the project grouped by type, with their UUIDs.

Returns {scripts: [...], scenes: [...], images: [...], prefabs: [...]}. Each entry has at minimum {rel, uuid}; images additionally include sprite_frame_uuid if the meta is upgraded.

Write a TypeScript script + its meta into the project.

rel_path can be either:

• bare name like 'GameManager' -> writes assets/scripts/GameManager.ts

• full path like 'assets/scripts/sub/Foo.ts'

Returns {path, rel_path, uuid}. The uuid is the standard 36-char form; use cocos_compress_uuid to get the 23-char form needed in scene files.

Copy a PNG into the project and write a complete sprite-frame meta.

Default: assets/textures/. Set as_resource=True to put it under assets/resources/ (needed for runtime loading via resources.load()).

Returns {path, rel_path, main_uuid, sprite_frame_uuid, texture_uuid}.

Upgrade a texture-only PNG meta to include a sprite-frame sub.

Cocos Creator's CLI --build auto-generates type: texture metas when it imports a fresh PNG. To reference such a PNG from cc.Sprite, run this tool to add the f9941 (sprite-frame) sub. Idempotent — does nothing if the sub already exists.

Returns the updated meta dict.

Return the <uuid>@f9941 sprite-frame sub-uuid for a PNG meta.

Set 9-slice border on an existing sprite-frame meta in pixels.

Required before using a PNG with cc.Sprite type=SLICED (rounded buttons, UI panels, dialog backgrounds — anything that should keep crisp corners while stretching the middle).

Idempotent. The meta must already be sprite-frame type (run cocos_upgrade_image_meta first if it's still texture-only).

List the tools actually registered on this MCP server.

Addresses stale-catalog scenarios where a subagent's MCP session can't reliably see tools registered after the session started — asking the server directly is the ground truth. Returns {count, tools: [{name, category, summary}, ...]} where summary is the first non-empty line of the docstring.

Filters (all optional):

• name_contains — case-insensitive substring on the tool name. Pass "joint" to list every Joint2D helper, "scaffold" for the 9 gameplay scaffolds.

• category — coarse bucket inferred from the name prefix: uuid / project / asset / scene / physics2d / physics3d / rendering / ui / media / build / interact / scaffold / composite / meta / other. Inference is heuristic — a tool shows up in exactly one bucket.

Empty filters return every tool. Use this whenever you need to double-check whether a capability is already baked in before implementing it manually.

Return commonly used Cocos Creator constants.

Saves you from looking up layer bitmasks, blend factors, alignment enum values, etc.

Pin a UI theme so every subsequent cocos_add_label / cocos_add_button / cocos_add_sprite call with color_preset=… / size_preset=… resolves through the same design tokens — produces a visually consistent game.

Built-in theme names: dark_game, light_minimal, neon_arcade, pastel_cozy, corporate. Pass a custom dict ({color, font_size, spacing, radius}) for something bespoke — missing preset names fall through to dark_game defaults so no lookup ever fails.

Preset vocabulary every theme MUST provide: color: primary / secondary / bg / surface / text / text_dim / success / warn / danger / border (10) font_size: title / heading / body / caption (4) spacing: xs / sm / md / lg / xl (5) radius: sm / md / lg / pill (4)

Calling with no args pins dark_game.

Return the project's active UI theme (fully resolved).

Always returns a complete theme — un-themed projects get the dark_game default with source='fallback'. Source is 'registry' when the project has explicitly pinned a theme.

Return all five bundled UI themes verbatim.

Useful for previewing the palette before pinning one, or as a starting point for a custom= override passed to cocos_set_ui_theme.

Generate a coherent UI palette from one brand color.

Given seed_hex (the game's primary/brand color) and a mode ("dark" or "light"), computes a full color set via HSL math:

• secondary = complementary hue

• bg / surface = seed hue at low saturation (subtle brand tint)

• text / text_dim = high-contrast against bg

• border = mid-lightness neutral

• success/warn/danger stay at fixed green/amber/red (severity readability trumps brand consistency)

Returns a {color: {...}} dict ready to pass through to cocos_set_ui_theme(project, custom=<this>). The caller may also merge in font_size / spacing / radius overrides before passing.

Typical use::

palette = cocos_derive_theme_from_seed("#6366f1", mode="dark")
cocos_set_ui_theme("/game", custom=palette)

Convert #rrggbb / #rgb / #rrggbbaa to RGBA ints.

Returns {r, g, b, a} suitable for any tool that takes color_r/color_g/color_b/color_a params. Lets the caller paste CSS / design-tool hex codes without hand-translating to int quadruples (a common source of off-by-one color bugs).

Create a minimal empty 2D scene + meta in assets/scenes/.

Includes Canvas + UICamera (cc.Camera) + cc.Canvas + Widget + SceneGlobals (Ambient/Skybox/Shadows) + PrefabInfo. The Camera's clearColor is set so a solid sky-blue background is visible even before any sprite is added.

Returns canonical IDs: {scene_path, scene_uuid, scene_node_id, canvas_node_id, ui_camera_node_id, camera_component_id, canvas_component_id}

These IDs are array-index references into the scene's JSON; use them as parent_id / node_id in subsequent tool calls.

Append a new cc.Node under parent_id, return its array index.

layer defaults to UI_2D (33554432). Use 1073741824 for the camera node. The new node has no components yet — call cocos_add_uitransform, cocos_add_sprite etc. to attach them.

Attach a cc.UITransform to a node. Required for any UI rendering.

Attach a cc.Sprite to a node.

sprite_frame_uuid is the <uuid>@f9941 form returned by cocos_add_image or cocos_get_sprite_frame_uuid. size_mode: 0=CUSTOM (use UITransform's contentSize), 1=TRIMMED, 2=RAW. color_preset: pick from the project's UI theme (e.g. "primary", "surface") to tint the sprite — overrides the explicit RGBA args.

Attach cc.Label. overflow: 0=NONE 1=CLAMP 2=SHRINK 3=RESIZE_HEIGHT. cache_mode: 0=NONE 1=BITMAP 2=CHAR. CLAMP truncates, SHRINK auto-shrinks font.

Design-token presets (override the equivalent explicit arg):

• color_preset: e.g. "text", "primary", "danger"

• size_preset: "title" | "heading" | "body" | "caption"

• outline_color_preset: e.g. "bg" for dark outline on light Set the theme once via cocos_set_ui_theme; un-themed projects fall back to dark_game defaults so presets always resolve.

Attach a cc.Graphics to a node (for runtime vector drawing).

Attach a cc.Widget for screen-anchor layout. align_flags is a bitmask.

Attach any cc component by its full type name (e.g. 'cc.RigidBody2D').

props values are auto-wrapped: list[3]->Vec3, int->id ref, etc. For resource refs pass {"uuid": ""}.

Attach a custom TypeScript script component to a node.

script_uuid_compressed is the 23-char short form (run cocos_compress_uuid on the .ts.meta uuid).

props lets you set @property fields. Pass int values for node/component refs (they'll be wrapped as {"id": N}). Pass strings/numbers/bools for plain values.

Set a @property on a component to reference another node/component.

Pass target_id=None to clear the reference.

Set a literal (non-reference) property on any scene object.

Use this for things like _string, _fontSize, _color, etc. For node/component references, use cocos_link_property instead.

Set a property to a uuid resource ref (SpriteFrame, AudioClip, etc.).

Set a node's local position (x, y, z). z defaults to 0 for 2D scenes.

Toggle a node's _active flag (True = visible/ticking, False = disabled).

Set a node's local scale.

Set 2D rotation (euler Z) in degrees.

Set a node's layer bitmask. Common: UI_2D=33554432, DEFAULT=1073741824.

Re-parent a node. sibling_index=-1 appends as last child.

Soft-delete a node (disconnect from parent, deactivate). Indices stay stable.

Shallow-copy a node (no children/components). Returns new node index.

Find the first node with the given name. Returns its array index, or None.

List every cc.Node in the scene with its id, name, parent, components, children.

Sanity-check a scene file: ref ranges, type tags, parent linkage.

Returns {valid: bool, object_count: int, issues: [...]}. Run this after building a scene to catch dangling id references before invoking cocos_build.

NOTE: structural-only. To check whether the scene's components match the project's enabled engine modules (the "build succeeds but RigidBody2D doesn't work" class of bugs), also call cocos_audit_scene_modules.

Declarative expectations against a scene/prefab — regression- test style.

Each entry in assertions:

{"path": "", "op": "", "value": }

with optional root-finder shortcuts:

{"find_node_by_name": "Player", # find first cc.Node _name "path": "_lpos.x", "op": "gt", "value": 0}

{"find_component": {"type": "cc.Sprite", "on_node_named": "Enemy"}, "path": "_color.r", "op": "eq", "value": 255}

Ops: eq / ne / gt / ge / lt / le / in / not_in / contains / match / is_null / not_null / type_is / exists / not_exists

Path syntax: _children[0].__id__ / 15._lpos.x. First dotted segment as int + root is list → list index. [N] always list index. Missing path → LookupError surfaces as a failed assertion (or passes if op=not_exists).

Runs EVERY assertion even if earlier ones fail — regression checks want a full report, not a first-failure bail.

Returns {ok, scene_path, total, passed_count, failed_count, passed: [...], failed: [...]}.

Non-structural UI quality check (complement to cocos_validate_scene).

Flags issues that build + load cleanly but produce bad UX:

• Button touch target below 44×44 (iOS HIG / Material 48dp min)

• Label overflow=NONE + wrap off in a box that likely clips the text

• UI component on a node with layer != UI_2D (UICamera won't render it)

Returns {ok, scene_path, warnings:[{rule, node_id, node_name, message}]}. All warnings are non-fatal; the caller decides what to fix.

Cross-check scene components against the project's engine.json.

Catches the single highest-frequency "build succeeded, game broken at runtime" failure: using a component (RigidBody2D, Spine, VideoPlayer, ...) whose engine module is currently disabled. Build produces artifacts, the scene loads, but the components silently do nothing.

project_path=None → walks up from the scene file looking for package.json. Pass explicitly when the scene lives outside the project (prefab library, template copy).

Returns {ok, project_path, required, enabled, disabled, actions}. When ok=False, actions lists copy-pasteable next steps (cocos_set_engine_module calls + the library clean that module changes need).

Return the total number of objects in the scene/prefab JSON array.

Return the raw JSON dict of a scene object (for debugging/inspection).

Create an empty .prefab in assets/prefabs/ with a single root node.

Drop a .prefab file into the scene as a child node — returns root id.

Reads the .prefab JSON, deep-copies its node tree (root + children + components), shifts every internal id reference, gives every cloned object a fresh _id, refreshes each cc.PrefabInfo.fileId so multiple instances of the same prefab don't alias, and parents the new root under parent_id.

Treats the prefab as unlinked (a one-shot copy). If you later edit the .prefab, instances already dropped into the scene will NOT update — re-instantiate to pick up the changes.

Pass any of name / pos_x / pos_y / pos_z / scale to override the root's defaults (otherwise the prefab's own values stay).

Extract a fully-configured scene subtree into a reusable .prefab.

The usual case: build your "Enemy" in a scratch scene with Sprite + RigidBody2D + Collider + Animation + script all wired, then save-as-prefab to spawn dozens. Without this, every copy requires re-running the same add_* stack against a new node.

Self-contained rule: every cc.Node referenced from inside the subtree (script field pointing at another Node, Button target, etc.) must already BE inside the subtree. External cc.Node refs raise with a message naming the offender — Cocos's prefab format has no way to express late-bound cross-scene refs, so silent clipping would produce a broken prefab. Asset UUID refs ({__uuid__: ...} for SpriteFrames, clips, meshes, other prefabs) survive unchanged; those travel through the asset DB.

Effects on scene_path: NONE (read-only). If you want the scene to now use an instance instead of the raw subtree: delete the source node, then cocos_instantiate_prefab the fresh prefab. That's a deliberately-explicit two-step so you don't lose the raw subtree on a misfired single call.

Returns {prefab_path, prefab_uuid, root_node_id (=1), object_count, source_root_name}.

Configure ambient lighting on the scene's cc.AmbientInfo.

Colors are floats 0..1 (NOT 0..255 — sky/ground colors in Cocos are normalized like material PBR inputs). Pass None to leave unchanged. sky_illum is in lux, default ~20000. The scene must have been created via cocos_create_scene (which auto-attaches AmbientInfo).

Configure the scene's cc.SkyboxInfo.

env_lighting_type: 0=HEMISPHERE_DIFFUSE (cheap default), 1=AUTOGEN_HEMISPHERE_DIFFUSE, 2=DIFFUSEMAP_WITH_REFLECTION (PBR, needs envmap).

envmap_uuid points at a cc.TextureCube asset. Pass empty string "" to clear. Pass None to leave fields unchanged.

Configure planar shadows on the scene's cc.ShadowsInfo.

normal: ground plane normal, defaults to (0, 1, 0) for flat ground. distance: signed offset along normal from world origin. color: shadow color, ints 0..255.

Pass None on any axis/channel to leave it unchanged. Enabling planar shadows also typically requires at least one DirectionalLight in the scene.

Configure volumetric fog on the scene's cc.FogInfo.

Fourth scene-global alongside ambient/skybox/shadows. Lazy-creates a cc.FogInfo + links it from cc.SceneGlobals if the scene doesn't have one yet (scenes built before this tool existed won't).

fog_type: 0=LINEAR (use start+end), 1=EXP (density), 2=EXP_SQUARED, 3=LAYERED (top+range). Atmospheric settings are inter-dependent — LINEAR ignores density, EXP/EXP_SQUARED ignore start/end.

PREFERRED for ≥3 sequential mutations on the same scene.

Execute multiple scene operations in a single file read/write cycle. ~80× faster than calling individual cocos_add_* / cocos_set_* tools when building more than a handful of nodes/components on the same scene; the file is parsed once, mutated in memory, and serialized once at the end.

Rule of thumb: if you would otherwise call cocos_add_*, cocos_attach_*, cocos_set_*, or cocos_link_* three or more times in a row on the same scene, use this tool instead. Pass all the ops in one call; use "$N" back-references for ids that earlier ops produced.

Each operation is a dict with an op key and operation-specific params. Returns {object_count, ops_executed, results, named_results}:

• results is the positional list (preserved for callers that use "$N" index back-refs).

• named_results is a dict keyed by the name field set on any op — ops without name don't contribute. Let's you use "$bird" instead of "$0" which stays stable across edits.

Supported ops: Structural: - {"op": "add_node", "parent_id": N, "name": "...", "lpos": [x, y, z]?, "lscale": [sx, sy, sz]?, "pos_x": ..., "pos_y": ..., "pos_z": ..., "sx": ..., "sy": ..., "sz": ..., "layer": L?, "active": true/false?, "sibling_index": -1?} (lpos / lscale tuple forms match direct sb.add_node; pos_x/y/z and sx/sy/sz scalars are the legacy form. Tuple wins when both supplied. Prior releases silently dropped lscale — every batch-created node was left at (1,1,1) regardless of op input.) - {"op": "attach_script", "node_id": N, "script_uuid_compressed": "...", "props": {...}} (36-char standard UUIDs auto-compressed, matching cocos_add_script.) - {"op": "link_property", "component_id": N, "prop_name": "...", "target_id": M} - {"op": "set_property", "object_id": N, "prop_name": "...", "value": ...} - {"op": "set_uuid_property", "object_id": N, "prop_name": "...", "uuid": "..."} - {"op": "set_position", "node_id": N, "lpos": [x, y, z]? OR "x": ..., "y": ..., "z": ...} - {"op": "set_scale", "node_id": N, "lscale": [sx, sy, sz]? OR "sx": ..., "sy": ..., "sz": ...} - {"op": "set_rotation", "node_id": N, "angle_z": deg} - {"op": "set_layer", "node_id": N, "layer": L} - {"op": "set_active", "node_id": N, "active": true/false}

Components: - {"op": "add_uitransform", "node_id": N, "width": W, "height": H, "anchor_x": ..., "anchor_y": ...} - {"op": "add_widget", "node_id": N, "align_flags": 45, "target_id": M?} - {"op": "add_sprite", "node_id": N, "sprite_frame_uuid": "...", "size_mode": 0} - {"op": "add_label", "node_id": N, "text": "...", "font_size": 40, "color_r"...} - {"op": "add_graphics", "node_id": N} - {"op": "add_camera", "node_id": N, "ortho_height": ..., "clear_color_r"...} - {"op": "add_mask", "node_id": N, "mask_type": 0, "inverted": false, "segments": 64} - {"op": "add_richtext", "node_id": N, "text": "Hi", "font_size": 40, ...} - {"op": "add_button", "node_id": N, "transition": 2, "zoom_scale": 1.1} - {"op": "add_layout", "node_id": N, "layout_type": 1, "spacing_x": ..., ...} - {"op": "add_progress_bar", "node_id": N, "mode": 0, "total_length": 100, "progress": 1.0, "bar_sprite_id": M?} - {"op": "add_audio_source", "node_id": N, "clip_uuid": "...", "volume": 1.0, "loop": false, "play_on_awake": false} - {"op": "add_animation", "node_id": N, "default_clip_uuid": "...", "clip_uuids": [...], "play_on_load": true} - {"op": "add_rigidbody2d", "node_id": N, "body_type": 2, ...} - {"op": "add_box_collider2d", "node_id": N, "width": W, ...} - {"op": "add_circle_collider2d", "node_id": N, "radius": R, ...} - {"op": "add_polygon_collider2d", "node_id": N, "points": [[x,y], ...], ...} - {"op": "add_component", "node_id": N, "type_name": "cc.X", "props": {...}}

Physics 2D joints (Cocos 3.8 has eight — all present): - {"op": "add_distance_joint2d", "node_id": N, "connected_body_id": M?, "distance": 100, ...} - {"op": "add_hinge_joint2d", "node_id": N, "enable_motor": true, "motor_speed": 50, ...} - {"op": "add_spring_joint2d", "node_id": N, "frequency": 5, "damping_ratio": 0.7, ...} - {"op": "add_mouse_joint2d", "node_id": N, "max_force": 1000, "target_x": ..., "target_y": ...} - {"op": "add_slider_joint2d", "node_id": N, "angle": 0, "enable_motor": true, ...} - {"op": "add_wheel_joint2d", "node_id": N, "angle": 90, ...} - {"op": "add_fixed_joint_2d", "node_id": N, "angle": 0, ...} (cc.FixedJoint2D — previously mis-named "weld"; 3.8 renames it.) - {"op": "add_relative_joint2d", "node_id": N, "linear_offset_x": 10, ...}

Back-reference forms inside any op value:

• "$N" — positional id of op index N (0-based).

• "$name" — named id, resolves against prior ops' name field.

Example mixing both forms::

[{"op": "add_node", "parent_id": 2, "name": "bird"}, # $0 or $bird {"op": "add_uitransform", "node_id": "$bird", "width": 50, "height": 50}, {"op": "add_rigidbody2d", "node_id": "$bird", "body_type": 2}, {"op": "add_circle_collider2d", "node_id": "$bird", "radius": 25}]

Attach cc.RigidBody2D. body_type: 0=Static, 1=Kinematic, 2=Dynamic.

Attach cc.BoxCollider2D with given size, offset, and physics material.

Attach cc.CircleCollider2D with given radius and physics material.

Attach cc.PolygonCollider2D. points is [[x,y],...] vertex list.

Attach cc.DistanceJoint2D — keeps two bodies a fixed distance apart.

Attach cc.HingeJoint2D — pivots around a shared anchor (door, wheel, pendulum).

Attach cc.SpringJoint2D — soft springy distance (suspensions, ropes).

Attach cc.MouseJoint2D — drag-to-target constraint, used to pick up bodies with the mouse.

Attach cc.SliderJoint2D — translates along an axis (elevators, pistons).

Attach cc.WheelJoint2D — wheel + axle (slide along axis + spring + motor combined; vehicles).

Attach cc.FixedJoint2D — rigidly fuses two bodies (breakable structures).

Named "weld" in Box2D; replaces the prior cocos_add_weld_joint2d which emitted cc.WeldJoint2D (not a real 3.8 class).

Attach cc.RelativeJoint2D — keeps relative position+angle ('attach to' effect).

Also covers the follow-target use case that the old cocos_add_motor_joint2d tried to solve; cc.MotorJoint2D does not exist in Cocos 3.8.

Attach cc.Button. transition: 0=NONE, 1=COLOR, 2=SCALE, 3=SPRITE.

color_preset (e.g. "primary", "secondary", "danger") sets normal_color from the project's UI theme AND auto-derives matching hover / pressed / disabled shades — pass explicit RGBA args only when you want to override those derived values.

click_events: list of dicts from cocos_make_click_event(). Each binds a button press to a script method. Example: evt = cocos_make_click_event(scene, gm_node, 'GameManager', 'onRestart') cocos_add_button(scene, btn_node, click_events=[evt])

Attach cc.Layout. layout_type: 0=NONE, 1=HORIZONTAL, 2=VERTICAL, 3=GRID.

Attach cc.ProgressBar. mode: 0=HORIZONTAL, 1=VERTICAL, 2=FILLED.

Attach cc.ScrollView. content_id points to the scrollable content node.

Attach cc.Toggle. check_events: list from cocos_make_event_handler().

Attach cc.EditBox. input_mode: 0=ANY, 6=SINGLE_LINE. -1=unlimited length.

Attach cc.Slider. slide_events: list from cocos_make_event_handler().

Attach cc.PageView (swipeable pages). direction: 0=H, 1=V.

Attach cc.ToggleContainer (radio group). Children are mutually exclusive.

Attach cc.ScrollBar — companion scroll indicator for a ScrollView.

direction: 0=HORIZONTAL (default), 1=VERTICAL. Pass scroll_view_id + handle_sprite_id to wire both references at attach time; otherwise set later via link_property.

Attach cc.PageViewIndicator — dots row that tracks PageView position.

Attach to a child of the PageView node. Engine auto-spawns one indicator sprite per page using sprite_frame_uuid as template. direction: 0=HORIZONTAL (default), 1=VERTICAL.

Attach cc.WebView — embedded browser pane for ToS / activity pages.

Build a cc.EventHandler dict for component event bindings.

Use with: cocos_add_scroll_view(scroll_events=[...]), cocos_add_toggle(check_events=[...]), cocos_add_slider(slide_events=[...]), cocos_add_editbox(editing_return=[...]).

Same pattern as cocos_make_click_event but for non-Button components.

Build a cc.ClickEvent dict for use with cocos_add_button's click_events.

Args: target_node_id: Node that holds the script (array index) component_name: @ccclass name (e.g. 'GameManager') handler: Method name to call (e.g. 'onStartClick')

Returns a dict to pass in click_events list of cocos_add_button.

Example workflow: evt = cocos_make_click_event(scene, gm_node, 'GameManager', 'onStart') cocos_add_button(scene, btn_node, click_events=[evt])

Attach cc.RigidBody (3D).

body_type: 1=DYNAMIC (default), 2=STATIC, 4=KINEMATIC. Values are engine's ERigidBodyType bitmask, NOT contiguous 0/1/2 like the 2D API. linear_factor / angular_factor lock motion on a per-axis basis (set component to 0 to freeze that axis, 1 for free movement).

Attach cc.BoxCollider (3D AABB shape).

Attach cc.SphereCollider (3D sphere shape).

Attach cc.CapsuleCollider. direction: 0=X, 1=Y (default), 2=Z.

Attach cc.CylinderCollider.

Attach cc.ConeCollider.

Attach cc.PlaneCollider — infinite plane, typically used for the ground.

Default normal (0, 1, 0) + constant 0 means the XZ plane at y=0.

Attach cc.MeshCollider.

IMPORTANT: convex=True is required when the rigid body is DYNAMIC — physics backends (PhysX/Bullet) only support convex meshes on non-static bodies. For static ground geometry, triangle (concave) meshes are fine with convex=False.

Attach cc.TerrainCollider (pass a cc.Terrain asset UUID).

Attach cc.BoxCharacterController — AABB-shaped kinematic character.

Use this INSTEAD of RigidBody + Collider for player movement. It handles ground snapping, slope limits, step-up automatically.

Attach cc.CapsuleCharacterController — capsule-shaped kinematic character.

More common than box for humanoid characters; smoother wall sliding. height is the distance between the two sphere centers (NOT total capsule height, which is height + 2*radius).

Create a cc.PhysicsMaterial (.pmat) asset. Returns {path, rel_path, uuid}.

Bind to a collider via cocos_set_uuid_property(collider_id, "_material", <uuid>).

Defaults match engine: friction=0.6, restitution=0 (no bounce). For bouncy materials set restitution 0.3-0.9; for ice set friction 0.02.

Attach cc.DirectionalLight — sun/moon parallel light.

illuminance is in lux (default 65000 ≈ midday sun). shadow_pcf: 0=HARD, 1=SOFT, 2=SOFT_2X, 3=SOFT_4X. A scene typically has exactly one directional light.

Attach cc.SphereLight — point-light with physical size (bulb, lantern).

term: 0=LUMINOUS_FLUX (default), 1=LUMINANCE. light_range is the falloff distance.

Attach cc.SpotLight — cone-shaped light (torch, stage spot).

Attach cc.MeshRenderer — renders a 3D mesh.

material_uuids: one per submesh; order matters. Pass None to wire later via cocos_set_uuid_property(id, "_mesh", uuid). shadow_casting: 0=OFF (default), 1=ON. shadow_receiving: 0=OFF, 1=ON (default). reflection_probe_type: 0=NONE, 1=BAKED_CUBEMAP, 2=PLANAR, 3=BLEND.

Attach cc.SkinnedMeshRenderer — MeshRenderer driven by a skeleton.

Use this for humanoid/animal characters imported from GLTF/FBX. skinning_root_node_id is the scene-array index of the armature root node created during model import (pass the Node id, not a UUID).

Attach cc.AudioSource. clip_uuid references an audio-clip asset.

Attach cc.Animation. clip_uuids is a list of AnimationClip asset UUIDs.