Skip to content

Commit f12ede6

Browse files
bobbyreedbobbyreed
authored
Merge pull request #13 from bobbyreed/tutorial-scene
Add comprehensive README with PixiJS and AI development documentation
2 parents 5c6c7c0 + 921b322 commit f12ede6

1 file changed

Lines changed: 248 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 248 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,254 @@
33
</p>
44

55
# ONE JUMP
6-
ramlife - where vertical distance is meaningless - a simple game to test-drive the PixiJS library
76

8-
# Tech Stack
9-
<img alt="pixi.js logo" src="/public/assets/pixiLogo.svg" height=100>
7+
> **"From Space to Campus in One Epic Descent"**
108
9+
A high-stakes vertical falling game where Starsky the Ram descends from the stars to Earth through 10 increasingly challenging atmospheric stages. Navigate through space debris, weather phenomena, and urban obstacles while performing daredevil tricks and near-misses for maximum points.
1110

12-
All images were created using generative AI. Used so far:
13-
- ChatGPT 5 Free
14-
- Google Gemini 2.5 Flash Free
11+
## 🎮 Features
12+
13+
- **10 Unique Atmospheric Stages** - Journey from Low Earth Orbit to the OCU campus
14+
- **Stage-Specific Visuals** - Parallax backgrounds with dynamic weather and environmental effects
15+
- **Risk/Reward Gameplay** - Thread the needle between obstacles for bonus points
16+
- **Trick System** - Perform aerial maneuvers for style points and combo multipliers
17+
- **Progressive Difficulty** - Each stage introduces new obstacles and mechanics
18+
- **Story-Driven Campaign** - Comic-style narrative panels between stages
19+
- **Leaderboard System** - Firebase-powered global and per-level rankings
20+
- **Interactive Tutorial** - Learn the ropes with guided practice mode
21+
- **Grading System** - Earn S through F ranks based on performance
22+
- **Star Collection** - Unlock content and track completion across all levels
23+
24+
## 🚀 Tech Stack
25+
26+
<img alt="pixi.js logo" src="/public/assets/pixiLogo.svg" height="100">
27+
28+
### PixiJS v8 - WebGPU Rendering Engine
29+
30+
This game showcases the power and flexibility of **PixiJS v8**, a modern 2D rendering library that leverages WebGPU for high-performance graphics.
31+
32+
#### Key PixiJS Features Utilized:
33+
34+
**Graphics & Rendering:**
35+
- **WebGPU Renderer** - Hardware-accelerated graphics with fallback to WebGL2
36+
- **Render Groups** - Optimized batching for UI, game objects, and particle layers
37+
- **Sprite System** - Efficient texture management and atlas support
38+
- **Graphics API** - Procedural shapes for obstacles, UI, and effects
39+
- **Particle Container** - High-performance particle systems (10,000+ particles)
40+
41+
**Scene Management:**
42+
- **Container Hierarchy** - Modular scene architecture (Menu, Game, Level Select, etc.)
43+
- **Display Object System** - Transform inheritance for camera and world positioning
44+
- **Masking & Clipping** - UI panels and viewport management
45+
46+
**Animation & Effects:**
47+
- **Ticker System** - Frame-perfect game loop and animation timing
48+
- **Sprite Animations** - Character state machines and obstacle behaviors
49+
- **Parallax Scrolling** - Multi-layer backgrounds with depth perception
50+
- **Particle Effects** - Speed lines, near-miss sparks, collision impacts
51+
52+
**Asset Management:**
53+
- **Assets API** - Lazy loading and bundle management per stage
54+
- **Texture Atlas** - Optimized sprite sheet packing
55+
- **Dynamic Loading** - On-demand asset streaming for story panels
56+
57+
**Performance Optimizations:**
58+
- **Object Pooling** - Reusable obstacle and particle instances
59+
- **Culling** - Only render visible objects
60+
- **Spatial Partitioning** - Efficient collision detection grid
61+
- **Resolution Scaling** - Device pixel ratio adaptation
62+
63+
### Additional Technologies
64+
65+
- **Firebase** - Authentication, Firestore database, and leaderboard hosting
66+
- **Vite** - Lightning-fast build tool and dev server
67+
- **ES6+ Modules** - Modern JavaScript architecture
68+
- **CSS Variables** - Theme-aware styling system
69+
70+
## 🤖 AI-Assisted Development
71+
72+
This project was built with extensive AI assistance, showcasing how modern AI tools can accelerate game development while maintaining high code quality.
73+
74+
### AI Tools Used
75+
76+
#### Claude 3.5 Sonnet (Primary Development Assistant)
77+
- **Architecture Design** - Scene management, collision systems, particle effects
78+
- **Feature Implementation** - Tutorial system, leaderboards, grading mechanics
79+
- **Code Refactoring** - Performance optimizations and bug fixes
80+
- **Documentation** - Inline comments and system explanations
81+
82+
#### ChatGPT-4 (Asset Generation)
83+
- **Image Generation** - Character sprites, story panels, UI elements
84+
- **Concept Art** - Level themes and visual style direction
85+
- **Prompt Engineering** - Iterative refinement of visual assets
86+
87+
#### Google Gemini 2.5 Flash (Supplemental Assets)
88+
- **Background Elements** - Atmospheric layers and environmental details
89+
- **UI Graphics** - Icons, buttons, and decorative elements
90+
91+
### Development Narrative
92+
93+
The game began as an experiment to explore PixiJS v8's new WebGPU capabilities. Initial prototyping focused on smooth scrolling mechanics and collision detection, quickly evolving into a full-featured arcade game.
94+
95+
**AI Collaboration Workflow:**
96+
97+
1. **Conceptual Phase** - Discussed game mechanics and visual style with Claude, establishing the "Duke Nukem meets mascot platformer" aesthetic
98+
2. **Technical Foundation** - Built scene management, physics engine, and rendering pipeline with AI-assisted architecture
99+
3. **Visual Development** - Generated 100+ story panels and sprites using ChatGPT and Gemini's image generation
100+
4. **Feature Expansion** - Iteratively added tutorials, leaderboards, and polish with AI suggesting optimizations
101+
5. **Bug Fixing** - Rapid debugging sessions with AI identifying edge cases and providing solutions
102+
103+
**Key AI Contributions:**
104+
105+
- **Code Generation Speed** - Complex systems like parallax backgrounds implemented in minutes vs. hours
106+
- **Best Practices** - AI suggested PixiJS v8 patterns like render groups and proper container hierarchies
107+
- **Problem Solving** - Collision detection refinement, landing zone protection, and combo system logic
108+
- **Asset Iteration** - Rapid visual prototyping with dozens of variations to find the right style
109+
110+
**Human Direction:**
111+
112+
- Game design decisions and difficulty balancing
113+
- Story writing and character personality
114+
- Final asset selection and curation
115+
- Gameplay feel and polish tuning
116+
117+
The result is a production-quality game built in a fraction of the traditional development time, demonstrating the synergy between human creativity and AI execution.
118+
119+
## 📦 Installation & Setup
120+
121+
### Prerequisites
122+
123+
- Node.js 18+ and npm
124+
- Modern browser with WebGPU support (Chrome 113+, Edge 113+, or WebGL2 fallback)
125+
126+
### Quick Start
127+
128+
```bash
129+
# Clone the repository
130+
git clone https://github.com/bobbyreed/one-jump.git
131+
cd one-jump
132+
133+
# Install dependencies
134+
npm install
135+
136+
# Start development server
137+
npm run dev
138+
```
139+
140+
The game will be available at `http://localhost:5173`
141+
142+
### Build for Production
143+
144+
```bash
145+
# Create optimized build
146+
npm run build
147+
148+
# Preview production build
149+
npm run preview
150+
```
151+
152+
## 🗂️ Project Structure
153+
154+
```
155+
one-jump/
156+
├── public/
157+
│ └── assets/ # Images, story panels, sprites
158+
├── src/
159+
│ ├── config/ # Game constants and configuration
160+
│ │ ├── Constants.js
161+
│ │ └── StageThemes.js
162+
│ ├── entities/ # Game objects
163+
│ │ ├── Player.js
164+
│ │ └── Obstacle.js
165+
│ ├── managers/ # System managers
166+
│ │ ├── LevelManager.js
167+
│ │ ├── FirebaseManager.js
168+
│ │ ├── LeaderboardManager.js
169+
│ │ ├── AssetManager.js
170+
│ │ └── SaveManager.js
171+
│ ├── scenes/ # Game scenes
172+
│ │ ├── MenuScene.js
173+
│ │ ├── GameScene.js
174+
│ │ ├── LevelSelectScene.js
175+
│ │ ├── StoryScene.js
176+
│ │ ├── LeaderboardScene.js
177+
│ │ └── TutorialScene.js
178+
│ ├── systems/ # Game systems
179+
│ │ ├── CollisionSystem.js
180+
│ │ ├── ObstacleManager.js
181+
│ │ ├── BackgroundManager.js
182+
│ │ ├── ParticleSystem.js
183+
│ │ └── InputManager.js
184+
│ ├── ui/ # UI components
185+
│ │ ├── HUD.js
186+
│ │ ├── Button.js
187+
│ │ └── ResultScreen.js
188+
│ ├── Game.js # Main game class
189+
│ └── main.js # Entry point
190+
├── docs/
191+
│ └── devDocs/
192+
│ └── gdd.md # Game Design Document
193+
└── package.json
194+
```
195+
196+
## 🎯 Development
197+
198+
### Key Systems
199+
200+
**Scene Management:**
201+
- Modular scene architecture with BaseScene inheritance
202+
- Smooth transitions with fade effects
203+
- Asynchronous asset loading per scene
204+
205+
**Physics Engine:**
206+
- Custom gravity and velocity system
207+
- Collision detection with spatial grid optimization
208+
- Near-miss detection with distance thresholds
209+
210+
**Scoring System:**
211+
- Base points for completion
212+
- Near-miss bonuses (50-300 points based on proximity)
213+
- Combo multipliers (up to 10x)
214+
- Time bonuses and grade calculation
215+
216+
**Stage Progression:**
217+
- 10 unique atmospheric environments
218+
- Dynamic obstacle generation based on level config
219+
- Progressive difficulty with new obstacle types
220+
221+
### Debug Features
222+
223+
- `Shift+U` - Unlock all levels (Level Select)
224+
- `Shift+D` - Toggle debug overlay (Game)
225+
- Firebase emulator support for local development
226+
227+
## 🎨 Credits
228+
229+
### Development
230+
- **Lead Developer** - Bobby Reed
231+
- **AI Development Assistant** - Claude 3.5 Sonnet (Anthropic)
232+
- **Game Engine** - PixiJS v8
233+
234+
### Art & Assets
235+
- **AI Image Generation** - ChatGPT-4, Google Gemini 2.5 Flash
236+
- **Character Design** - Starsky the Ram, OCU Mascot
237+
- **Visual Style** - 80s/90s arcade inspired
238+
239+
### Special Thanks
240+
- Oklahoma City University for mascot inspiration
241+
- PixiJS community for documentation and examples
242+
- Firebase for backend infrastructure
243+
244+
## 📄 License
245+
246+
This project is private and proprietary.
247+
248+
## 🔗 Links
249+
250+
- [Game Design Document](docs/devDocs/gdd.md)
251+
- [PixiJS Documentation](https://pixijs.com/8.x/guides)
252+
- [Firebase Documentation](https://firebase.google.com/docs)
253+
254+
---
255+
256+
**Made with ❤️ using PixiJS v8 and AI assistance**

0 commit comments

Comments
 (0)