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.