Pixel Post Special Instructions Overview This document outlines special instructions for developing Pixel Post, a 2D retro game for the Orange Vibe Jam (deadline: May 15, 2025). The game uses a 2D pixel art visual style, arrow key movement, and placeholder 2D graphics, with code structured to support externally generated 2D assets. It is built with JavaScript, HTML, Tailwind CSS, and a 2D JavaScript framework (PixiJS recommended). These instructions ensure the prototype aligns with the game’s scope and technical requirements. Special Instructions 2D Pixel Visual Style
Style: The game adopts a 2D pixel art aesthetic inspired by Pokémon’s 2D era (e.g., Game Boy Advance). Sprites and backgrounds should have a retro, blocky look with a vibrant orange-heavy palette to match the Orange Vibe Jam theme. Implementation: Use placeholder 2D pixel art assets (e.g., simple colored squares or basic shapes) for prototyping to save time. Examples: bike (orange rectangle), houses (grey squares), mailboxes (small red squares), Orange Keepsakes (orange circles for stamps/letters/parcels). Structure code to load externally generated 2D pixel art assets (from Kenney.nl or custom creations) without altering logic. Use a sprite sheet or individual PNG files with consistent naming (e.g., bike.png, stamp.png). Apply an orange palette (e.g., #FF6200, #FFA500) for key elements (bike, Keepsakes, UI borders) to emphasize the theme. Visual progression: Level 1 (dim houses), Level 2 (orange banners), Level 3 (orange lanterns, fireworks). Code should support swapping background and sprite assets per level.
PixiJS Notes: Use PixiJS’s Sprite class for rendering 2D assets (e.g., PIXI.Sprite.from('bike.png')). Organize assets in a JSON config (e.g., { bike: 'assets/bike.png', stamp: 'assets/stamp.png' }) for easy replacement. Apply pixel-perfect rendering with app.renderer.roundPixels = true and PIXI.settings.SCALE_MODE = PIXI.SCALE_MODES.NEAREST to maintain retro aesthetic.
Arrow Key Movement
Mechanics: The player controls a bike using arrow keys for movement. Left/Right Arrows: Move bike horizontally across the screen (x-axis). Spacebar: Toss orange envelopes toward mailboxes (separate mechanic, not tied to movement). No Up/Down: Keep movement 2D side-scrolling to simplify controls and scope.
Implementation: Use JavaScript’s keydown and keyup event listeners to detect arrow key inputs. Update bike’s x-position based on key state (e.g., if (keys.left) bike.x -= speed). Cap bike movement within screen bounds (e.g., bike.x = Math.clamp(bike.x, 0, canvas.width)). Speed: Set bike speed to ~5 pixels/frame for smooth, responsive movement (adjust during testing). Collision: Detect bike-to-puddle collisions to reduce speed (e.g., speed *= 0.5 when in puddle).
PixiJS Notes: Represent bike as a PIXI.Sprite with a position (x, y). Update position in PixiJS’s game loop (app.ticker.add()). Use a simple state object for keys (e.g., keys = { left: false, right: false }).
Placeholder 2D Graphics
Approach: Use minimal placeholder graphics during prototyping to focus on mechanics, with code designed to seamlessly integrate externally generated 2D pixel art assets later. Placeholder Graphics: Bike: Orange rectangle (32x16 pixels). Houses: Grey squares (64x64 pixels) with red mailbox triangles (16x16 pixels). Orange Keepsakes: Orange circles (16x16 pixels) for stamps, letters, parcels (differentiated by size or border). Puddles: Blue ovals (32x16 pixels). Background: Solid grey (Level 1), grey with orange lines (Level 2), grey with orange dots (Level 3). UI: Orange-bordered text boxes (drawn as rectangles) for dialogues.
Code for External Assets: Use PixiJS’s asset loader (PIXI.Assets.load()) to preload images (e.g., await PIXI.Assets.load('assets/bike.png')). Name placeholders and final assets identically (e.g., bike.png) to avoid code changes when swapping. Support sprite sheets for efficiency (e.g., PIXI.Spritesheet for bike animations like wheel spin). Store asset paths in a config file (e.g., assets.json) for easy updates:{ "bike": "assets/bike.png", "stamp": "assets/stamp.png", "letter": "assets/letter.png", "parcel": "assets/parcel.png", "house": "assets/house.png" }
Ensure placeholders have same dimensions as final assets (e.g., bike: 32x16, house: 64x64) to avoid scaling issues.
Polish Phase: Replace placeholders with Kenney.nl or custom 2D pixel art (budget ~1 hour for integration). Test sprite alignment and animations (e.g., bike wheel spin, Keepsake sparkle).
Tech Stack: JS/HTML/Tailwind and PixiJS
JavaScript/HTML: Use a single HTML file (index.html) for the game, with a for PixiJS rendering and a
Tailwind CSS: Style React UI components (score, inventory, dialogue boxes) with Tailwind for rapid development. Apply orange-themed classes (e.g., bg-orange-500, border-orange-600) for UI elements. Use Tailwind’s utility-first approach for pixel art-style borders (e.g., border-4 border-orange-600 for dialogue boxes). Keep CSS minimal to avoid conflicts with PixiJS’s canvas rendering.
2D Framework: PixiJS (Recommended): Why PixiJS Over Phaser: PixiJS is lightweight, focused on 2D rendering, and ideal for pixel art with crisp scaling (SCALE_MODES.NEAREST). Faster setup for simple games (no built-in physics like Phaser, which is overkill for Pixel Post’s collision needs). Better performance for canvas rendering with many sprites (e.g., houses, Keepsakes). Easier integration with React/Tailwind for UI, as PixiJS handles only the game canvas.
PixiJS Setup: Include via CDN: https://cdn.jsdelivr.net/npm/[email protected]/dist/pixi.min.js. Initialize PixiJS app: const app = new PIXI.Application({ width: 800, height: 600, backgroundColor: 0xaaaaaa }). Add canvas to HTML: document.body.appendChild(app.view). Use app.ticker for game loop (move bike, update collisions, animate sprites). Implement collision detection manually (e.g., rectangle-based for bike-to-puddle, envelope-to-mailbox, bike-to-Keepsake).
Key Features: Sprite rendering for bike, houses, Keepsakes, puddles. Basic animations (e.g., bike wheel spin via sprite sheet, Keepsake sparkle via alpha tween). Text rendering for debug (e.g., score in canvas) until React UI is integrated.
Alternative: Phaser: If Phaser is preferred (e.g., for built-in physics or familiarity), use Phaser 3 with Arcade Physics for simple collisions. Include via CDN: https://cdn.jsdelivr.net/npm/[email protected]/dist/phaser.min.js. Setup: new Phaser.Game({ type: Phaser.AUTO, width: 800, height: 600, physics: { default: 'arcade' } }). Downsides: Heavier framework, steeper learning curve for React integration, less pixel-perfect control than PixiJS. Recommendation: Stick with PixiJS unless Phaser’s physics or scene management is critical.
Implementation Notes
Prototype (10 Hours): PixiJS Setup (1h): Initialize canvas, load placeholder assets, render bike sprite. Arrow Key Movement (1.5h): Implement bike movement (left/right), bound to screen, with speed reduction in puddles. Tossing Mechanic (1.5h): Code spacebar to toss envelopes, detect mailbox collisions (rectangle-based). Keepsake Collection (1h): Spawn 3–5 Keepsakes per level, detect bike collisions, update React inventory state. Level Layout (2h): Place 5–8 houses, mailboxes, puddles, Keepsakes per level. Code level-specific backgrounds. React UI (2h): Build score, inventory, dialogue callouts with Tailwind (orange-themed, pixel art borders). Sound (1h): Add placeholder sound effects (freesound.org) for toss, pickup, delivery.
Polish Phase (7 Days): Replace placeholders with Kenney.nl or custom 2D pixel art (~1h). Add animations (bike wheel, Keepsake sparkle, house glow) using PixiJS tweens or sprite sheets (~1 day). Refine Tailwind UI (orange palette, Pokémon-style fonts like “Press Start 2P”, ~1 day). Test collisions and pacing (~1.5 days).
Asset Integration: Ensure external assets match placeholder dimensions (e.g., bike: 32x16, house: 64x64). Use PixiJS’s Assets.load() or Spritesheet for smooth integration. Budget ~45 min for recoloring assets to orange palette in polish phase.
Risks: PixiJS learning curve: Use Copilot for boilerplate (e.g., sprite setup, game loop) to hit 80% AI code goal. Tailwind/React integration: Keep UI separate from PixiJS canvas to avoid conflicts (e.g., render UI in
Notes
Scope: Focus on core mechanics (biking, tossing, collecting) with placeholders to meet 10-hour prototype deadline. External assets swap in during polish. Orange Vibe: Emphasize orange palette in placeholders (bike, Keepsakes, UI) and final assets (recolored Kenney.nl sprites). Pokémon Style: Pixel art, arrow key movement, and simple collisions mimic 2D Pokémon’s feel. Dialogue callouts enhance story without NPC complexity. Framework Choice: PixiJS is recommended for lightweight 2D rendering and pixel-perfect control. Phaser is viable but heavier for this scope. Assets: Placeholders are simple shapes; final assets from Kenney.nl or custom, loaded via PixiJS. Sound from freesound.org. AI Tools: Use Copilot/Cursor for PixiJS boilerplate, collision logic, and React components to hit 80% AI code requirement.