# Cocos Ball Physics Gameplay

> Build and tune Cocos Creator ball-physics mini games and arcade prototypes. Use when Codex works on basketball, pinball, rolling balls, rebound walls, flippers, seesaws, tilting boards, catapult boards, ball launch arcs, ball rolling/sliding, sticking, micro-bounce, restitution/friction tuning, or mouse/keyboard control of physical boards and paddles in Cocos.

- Skill: `hzq510473048/cocos-ball-physics-gameplay` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add hzq510473048/cocos-ball-physics-gameplay`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hzq510473048/cocos-ball-physics-gameplay/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hzq510473048 (https://skillmd.com/u/hzq510473048)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hzq510473048/cocos-ball-physics-gameplay

---


# Cocos Ball Physics Gameplay

Use this skill below `ai-mini-game-development` and `cocos-ai-automation-development`.

- Use `ai-mini-game-development` for phase discipline, risk gates, user confirmation, and development logs.
- Use `cocos-ai-automation-development` for Cocos Creator, MCP, scene/assets/components, script hot reload, and preview validation.
- Use this skill for the gameplay domain: ball motion, physical surfaces, rebound behavior, launch mechanics, board/flipper controls, and tuning symptoms.

## Core Workflow

1. Preserve a validation baseline.
   - Keep the simplest working ball/board/wall scene available.
   - Build formal gameplay in a separate scene or clearly separated script.
   - Compare regressions against the validation scene before retuning from scratch.

2. Prove motion before polish.
   - First verify ball spawn, gravity, collision, rebound, rolling, reset, and player input.
   - Only then upgrade textures, lighting, camera polish, scoring, or level content.
   - If Cocos iteration is slow or ambiguous, make a minimal HTML/canvas or plain math demo for the motion rule, then port the rule back to Cocos.

3. Use physics first, then narrow assists.
   - Prefer real rigid bodies/colliders for the ball and contact surfaces.
   - Add scripted assists only when the desired arcade behavior is unreadable or unreliable in Cocos/Bullet.
   - Gate each assist by contact band, impact speed, active side, board angular velocity, cooldown, and gameplay state.

4. Separate natural physics from player action.
   - Natural board contact should let the ball bounce/roll without waiting for player input.
   - Player launch should require deliberate board movement, correct side/timing, and contact.
   - Do not turn the game into a pure trigger-launch mechanic unless that is explicitly the design.

5. Tune one symptom per pass.
   - Classify feedback as bounce, sticking, rolling, launch arc, input mapping, camera readability, or performance.
   - Change the smallest parameter set that addresses that symptom.
   - Validate with preview and, when scripts changed, `script_hot_reload`.

## Scene Pattern

A reliable first playable ball-physics setup is:

- dynamic ball rigid body with a sphere collider,
- kinematic board/flipper controlled by script,
- static or kinematic walls/guards with box colliders,
- visible fall/kill area below gaps,
- fixed camera based on the validated view,
- serialized controller properties for all feel constants.

Keep collider scale, visual mesh scale, and camera perspective aligned. If a ball looks embedded, flattened, or disconnected from the surface, inspect collider radius, contact offset/top height, mesh scale, board thickness, and camera angle together.

## References

Read only the reference that matches the current problem:

- `references/physics-patterns.md`: use for Cocos ball physics architecture, rebound, rolling, sticking, micro-bounce, scripted assists, and launch mechanics.
- `references/input-patterns.md`: use for keyboard/mouse/touch control of boards, paddles, flippers, seesaws, drag mapping, and raycast interactions.
- `references/tuning-guide.md`: use when translating subjective playtest feedback into concrete parameter or code changes.

## Validation Checklist

Before saying a ball-physics Cocos task is done:

- The target scene is explicitly opened and saved.
- The ball can spawn, collide, rebound or settle, roll/slide as intended, and reset/fail.
- Player input affects only the intended board/flipper/paddle behavior.
- Launches have readable arcs and can fail or vary when timing/angle is wrong, if the game design expects skill.
- No broad correction script creates magnetic sticking, endless micro-bounce, teleport-like state jumps, or fake static waiting.
- `script_hot_reload` or equivalent checks confirm changed gameplay scripts are present in generated editor/preview code.