hwihwalab commited on
Commit
2e12b16
ยท
verified ยท
1 Parent(s): 3ffef1b

Upload README_EN.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README_EN.md +150 -0
README_EN.md ADDED
@@ -0,0 +1,150 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ๐Ÿฌ Jelly Bean PlayEngine: 10 Pop Physics Bricks (English Documentation)
2
+
3
+ [![Language: English](https://img.shields.io/badge/Language-English-007ACC)](#) [![Language: ํ•œ๊ตญ์–ด](https://img.shields.io/badge/Language-ํ•œ๊ตญ์–ด-7cb342)](README_KR.md) [![Model Hub](https://img.shields.io/badge/๐Ÿค—%20Model%20Hub-PlayEngine-yellow)](https://huggingface.co/hwihwalab/mujoco-physics-playengine) [![๐Ÿค— Spaces Live Deck](https://img.shields.io/badge/๐Ÿค—%20Spaces%20Live-PlayEngine-blue?logo=huggingface)](https://huggingface.co/spaces/hwihwalab/mujoco-physics-playengine) [![HWIHWA LAB](https://img.shields.io/badge/Research%20Lab-HWIHWA%20LAB-d0f991?labelColor=050807)](https://huggingface.co/hwihwalab) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
4
+
5
+ > โ€œ**Jelly Bean PlayEngine: 10-in-1 Cute Playable Physics Arcade & Physical AI Sandbox | HWIHWA LAB**
6
+ > A high-performance interactive physics playground and autonomous robotics sandbox built on Google DeepMind's MuJoCo v3.3.0 physics engine (500Hz PGS numerical solver, $dt=0.002\text{s}$) and 30 FPS zero-latency browser streaming. Features 10 standalone procedural physics bricks, autonomous robotics controllers (LQR inverted pendulum balancer, Pure Pursuit waypoint navigation, 3-stage Inverse Kinematics claw rescue, ballistic demolition sniper), 3-way camera perspective switching, and zero-asset procedural 8-bit chiptune audio synthesis.โ€
7
+ > *Developed by [HWIHWA LAB](https://huggingface.co/hwihwalab) ยท AI ร— Automation ร— Aesthetics โœจ*
8
+
9
+ <div align="center">
10
+ <img src="assets/banner.png" alt="Jelly Bean PlayEngine 10 Physics Bricks" width="100%" style="border-radius: 16px; margin: 16px 0;">
11
+ </div>
12
+
13
+ ---
14
+
15
+ ## โšก Real-Time Physics & Robotics Architecture
16
+
17
+ **Jelly Bean PlayEngine** transforms academic multi-body dynamics into a vibrant, high-performance 3D arcade. Built on **MuJoCo v3.3.0** with a 500Hz numerical solver (`dt=0.002s`) and 30 FPS MJPEG browser streaming, it delivers zero-latency interactive physics with 100% procedural geometric assets, autonomous robotics controllers (LQR, Pure Pursuit, Inverse Kinematics), and pure Web Audio API sound synthesis.
18
+
19
+ * **500Hz PGS Solver**: Differential timestep $dt=0.002\text{s}$ with Projected Gauss-Seidel contact solver solves multi-body collisions, non-linear double pendulums, and friction cones accurately.
20
+ * **Zero-Latency 30 FPS Browser Streaming**: Headless server rendering feeds smooth, continuous MJPEG frames without requiring a dedicated high-end GPU on the client.
21
+ * **0-Byte Procedural Assets**: Zero external textures or 3D meshes to download; everything is synthesized via MuJoCo XML and Web Audio API oscillators.
22
+
23
+ ---
24
+
25
+ ## โญ The 4 Major System Upgrades
26
+
27
+ 1. **๐Ÿ† Game-Specific Victory Banners with Confetti & Fanfares**:
28
+ - Every mini-game features clear win conditions (e.g., `DOMINO CLEARED!`, `ALL COINS COLLECTED!`, `PINK BEAN WINS!`, `360ยฐ LOOP MASTER!`, `TOWER ANNIHILATED!`, `GOLDEN BALANCER!`).
29
+ - Celebrated with dynamic canvas particle confetti explosions and browser-synthesized brass fanfares.
30
+ 2. **๐ŸŽฅ 3-Way Camera Perspective Switcher**:
31
+ - Seamlessly switch between **Front View (`cam_front`)**, **45ยฐ Quarter Isometric (`cam_quarter`)**, and **Top-Down Aerial (`cam_topdown`)** with a single click or by pressing the **[C]** key.
32
+ 3. **๐ŸŽต Kawaii 8-Bit Chiptune BGM (Pure Web Audio API)**:
33
+ - Zero-byte download footprint: 100% procedurally synthesized in JavaScript via Web Audio API oscillators.
34
+ - Upbeat pentatonic arpeggios with syncopated bouncy bassline. Toggle on/off anytime via the top header button `[๐ŸŽต BGM ON/OFF]`.
35
+ 4. **๐Ÿค– 10-Game Smart AI Autonomous Controllers**:
36
+ - In addition to human manual keyboard control, press **[M]** or click **[๐Ÿค– SMART AI]** to engage autonomous robotics controllers:
37
+ - **Game 01**: 1.6s Optimal Rhythm Drop AI
38
+ - **Game 02**: Ball Pool Dual-Flipper Reaction Reflex AI
39
+ - **Game 03**: Ballistic Domino Impact Striker AI
40
+ - **Game 04**: Phase-Resonance 360ยฐ Swing Momentum Pumping AI
41
+ - **Game 05**: Double Pendulum Acrobat Kick AI
42
+ - **Game 06**: Hydrodynamic Slipstream Photo-Finish Boost AI
43
+ - **Game 07**: LQR Inverted Pendulum Lollipop Cart Balancer AI
44
+ - **Game 08**: Pure Pursuit Autonomous Navigation & 5-Coin Collector AI
45
+ - **Game 09**: 3-Stage Inverse Kinematics (IK) Plushie Claw Rescue AI
46
+ - **Game 10**: Center-of-Mass (CoM) Ballistic Demolition Sniper AI
47
+
48
+ ---
49
+
50
+ ## ๐Ÿงธ The 10 Pop Physics Mini-Games & Controls
51
+
52
+ ### ๐ŸŽฎ Universal Global Keyboard Shortcuts
53
+ | Key | Function | Description |
54
+ |:---:|:---|:---|
55
+ | **`Space`** | **Primary Action Trigger** | Start simulation / Drop bean / Flap pinball rain / Strike domino / Acrobatic kick / Fire cannon |
56
+ | **`R`** | **Instant Reset** | Rebuilds arena and resets all objects, timers, and HUD metrics to initial ready state |
57
+ | **`C`** | **Cycle 3-Way Camera** | Switches perspective instantly: `Front ๐ŸŽฅ` โž” `45ยฐ Quarter ๐Ÿ“` โž” `Top-Down ๐Ÿš` |
58
+ | **`M`** | **Smart AI / Manual Mode** | Toggles between Human Manual Control and Autonomous Smart AI Auto-Pilot |
59
+ | **`F`** | **16:9 Widescreen Fullscreen** | Toggles immersive full-screen arcade viewport |
60
+
61
+ ### ๐Ÿ•น๏ธ 10 Mini-Games Dual Controls (WASD & Arrow Keys)
62
+ | # | Game Title | MuJoCo Physics Core | Target Goal & Win Condition | Controls (Dual WASD & Arrow Keys) |
63
+ |---|------------|---------------------|-----------------------------|-----------------------------------|
64
+ | **01** | **Jelly Bean Skydiving Party** | Multi-Agent Gravity & Floor Impact | Drop beans from the sky to safely pile up on foam mat | `Space`: Drop Extra Bean, `R`: Reset |
65
+ | **02** | **Ball Pool Pinball Carnival** | Multi-Body Elastic Collision & Contact | Flip bumpers to bounce gumballs and score 1,000 pts | `A`/`D` or `โ†`/`โ†’`: Left/Right Flippers, `Space`: Rain |
66
+ | **03** | **Domino Knockdown Strike** | Kinetic Chain Reaction & Momentum Transfer | Topple 7 dominoes to strike down the Gold Star target | `Space`: Strike 1st Domino, `R`: Reset |
67
+ | **04** | **Giant Carnival Swing 360ยฐ** | Revolute Joint Kinematics & Resonance | Rhythm pumping to overcome gravity and execute a 360ยฐ loop | `W`/`โ†‘` or `Space`: Momentum Pump, `R`: Reset |
68
+ | **05** | **Jelly Bean Acrobatic Twin** | Double Pendulum Chaotic Dynamics | Direct joint torque & aerial 3x somersault combo in the sky | `W`/`S` or `โ†‘`/`โ†“` (Joint 1), `A`/`D` or `โ†`/`โ†’` (Joint 2), `Space`: Chaos Kick |
69
+ | **06** | **Waterpark Candy Slide Race** | Incline Tribology & Coulomb Friction | Pink Bean vs Mint Bean! Slide down rainbow ramp to splash pool | `Space`: Start, `A`/`โ†`: Pink Boost, `D`/`โ†’`: Mint Boost |
70
+ | **07** | **Pudding Cart Balancer (โญ Flagship)** | **CartPole / Inverted Pendulum (RL)** | Balance Pink Bean on cart for 15s to win Golden Balancer | `A`/`D` or `โ†`/`โ†’`: Push Cart, `M`: AI Mode |
71
+ | **08** | **Bumper Car Coin Collector** | **4-Wheel Chassis & Traction Dynamics** | Drive bumper car around arena to collect all 5 Star Coins | `W`/`S`/`A`/`D` or `โ†‘`/`โ†“`/`โ†`/`โ†’`: Drive & Steer (Compound Hold) |
72
+ | **09** | **Toy Claw Machine & Plushie Bean** | **2-DOF Robotic Arm (Robotics)** | Position robotic arm and activate magnetic grip to rescue plushie | `W`/`S` or `โ†‘`/`โ†“`: Shoulder, `A`/`D` or `โ†`/`โ†’`: Elbow, `Space`: Magnet |
73
+ | **10** | **Macaron Tower & Cannonball Bean** | Multi-Body Structural Collapse & Ballistics | Adjust cannon power and fire cannonball to crush 9-story tower | `Space`: Fire Cannon, `W`/`S` or `โ†‘`/`โ†“`: Power (0.4x~2.5x) |
74
+
75
+ ---
76
+
77
+ ### ๐Ÿ•น๏ธ Analysis of Game Control Paradigms (5 Distinct Types)
78
+ Each game utilizes a physical interaction paradigm tailored to its underlying dynamics:
79
+ 1. **Single-Shot Trigger**:
80
+ - **01 Skydiving** / **03 Domino** / **10 Cannon**: Press `Space` once to trigger ballistic trajectories and collapse.
81
+ 2. **Continuous Force Hold**:
82
+ - **02 Pinball**: Hold `A`/`D` or `โ†`/`โ†’` to keep flippers energized; release to return via spring physics.
83
+ - **07 Cart Balancer**: Hold `A`/`D` or `โ†`/`โ†’` to continuously apply lateral force to the cart.
84
+ 3. **Resonance Rhythm Pumping**:
85
+ - **04 Giant Swing**: Tap `W` / `โ†‘` / `Space` in phase with angular velocity to pump resonance energy towards a 360ยฐ loop.
86
+ 4. **Multi-Joint Actuation**:
87
+ - **05 Acrobatic**: `W`/`S` controls shoulder joint torque, `A`/`D` controls elbow torque, and `Space` executes an aerial flip.
88
+ - **09 Claw Crane**: `W`/`S` adjusts shoulder angle, `A`/`D` adjusts elbow angle, and `Space` toggles magnetic suction.
89
+ 5. **Compound Multi-Key Steering**:
90
+ - **08 Bumper Car**: Simultaneous multi-key input (`W`+`D` or `โ†‘`+`โ†’`) allows drifting and turning simultaneously.
91
+
92
+ ---
93
+
94
+ ## ๐Ÿ’ป Run Locally (Standalone Desktop App Mode)
95
+
96
+ Run in native desktop cockpit mode without web browser chrome or address bars:
97
+
98
+ ```bash
99
+ # 1. Clone repository
100
+ git clone https://huggingface.co/spaces/hwihwalab/mujoco-physics-playengine
101
+ cd mujoco-physics-playengine
102
+
103
+ # 2. Install dependencies (6 lightweight packages)
104
+ pip install -r requirements.txt
105
+
106
+ # 3. Launch Standalone Cockpit Window
107
+ python run.py
108
+ ```
109
+ *(Windows users can simply double-click `PlayEngine.bat` to launch instantly)*
110
+
111
+ ---
112
+
113
+ ## ๐Ÿ“ฆ Copy Standalone Physics Brick Code
114
+
115
+ Click the **`[๐Ÿ“‹ COPY PYTHON / XML CODE]`** button in the bottom right corner of the cockpit to copy standalone snippets:
116
+ 1. **`Python Script` tab**: Self-contained script launching MuJoCo's official native 3D viewer window with real-time AI and physics (`pip install mujoco`).
117
+ 2. **`MuJoCo XML (Blueprint)` tab**: Pure declarative physics XML scene for C++, Rust, Unity, Unreal, or Gymnasium reinforcement learning environments.
118
+
119
+ ---
120
+
121
+ ## ๐Ÿ“‚ Repository Contents
122
+
123
+ * `README.md`: Official Model Card overview on Hugging Face Model Hub.
124
+ * `README_EN.md`: Comprehensive English manual (this document).
125
+ * `README_KR.md`: Comprehensive Korean manual ([ํ•œ๊ตญ์–ด ๋งค๋‰ด์–ผ](README_KR.md)).
126
+ * `mujoco_playengine_bundle.zip`: Full production bundle containing all 10 MuJoCo procedural physics bricks, LQR/IK controllers, FastAPI server, and zero-asset Cybernetic Bento web cockpit.
127
+ * `assets/banner.png`: Official 16:9 3D rendered showcase cover banner.
128
+ * `LICENSE`: Official Apache 2.0 open-source license.
129
+
130
+ ---
131
+
132
+ ## ๐Ÿ‘ค About HWIHWA LAB
133
+
134
+ > *โ€œAI ร— Automation ร— Aesthetics โ€” Crafting tools you'll love โœจโ€*
135
+
136
+ **HWIHWA LAB** is an independent AI research & engineering studio dedicated to blending **practical on-device intelligence, autonomous operations, and refined aesthetics**. We engineer resilient systems that free solopreneurs and indie creators from operational overheadโ€”giving people their time and creative joy back.
137
+
138
+ ### ๐ŸŒ Physical AI & Robotics Ecosystem (Cross-Links)
139
+ - **Official Hub**: [๐Ÿค— Hugging Face (@hwihwalab)](https://huggingface.co/hwihwalab)
140
+ - ๐Ÿฌ **Physics Bricks & Web Arcade**: [mujoco-physics-playengine](https://huggingface.co/spaces/hwihwalab/mujoco-physics-playengine) *(Current Project)*
141
+ - ๐Ÿ•น๏ธ **Inverted Pendulum Control (PPO)**: [cartpole-v1-ppo](https://huggingface.co/hwihwalab/cartpole-v1-ppo)
142
+ - ๐Ÿค– **Bimanual Robotic Manipulation**: [act-aloha-sim-transfer-cube](https://huggingface.co/hwihwalab/act-aloha-sim-transfer-cube)
143
+ - ๐Ÿฆ† **3D Bipedal Locomotion & Teleop**: [microduck-3d-bipedal-teleop](https://huggingface.co/spaces/hwihwalab/microduck-3d-bipedal-teleop)
144
+ - ๐Ÿซ **Indie Game Studio Decision Brain**: [CHOCO-BRAIN-v1](https://huggingface.co/hwihwalab/connectailab-CHOCO-BRAIN-v1)
145
+
146
+ ---
147
+
148
+ ## ๐Ÿ“œ License
149
+
150
+ Distributed under the Apache 2.0 License. See `LICENSE` for details.