cocos_batch_scene_ops

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}]