OBSI - One Button Santa Invaders

One Button. Three Moves. Infinite Possibilities.

Classic arcade shooter reimagined with a single button that does it all. Tap to dodge. Hold to charge up while time slows. Release to fire a devastating shot and burst away at lightning speed.

Every press is a split-second decision: play it safe with quick taps, or risk everything to unleash explosive power. Master the rhythm, survive the waves, and discover how much depth one button can hold.

Part of the PICO-8 Advent Calendar 2025 — a new game each day!

"The seed has sprouted in fantasy console soil. Soon, it spreads roots deeper..."

---

How to Play

The Magic Combo (❎ or Left Mouse Button)

🎮 PRESS and RELEASE

• Instantly reverse direction
• Maintains auto-fire
• Your primary dodge tool

⚡ HOLD (1 seconds to charge)

• Movement slows to 20% speed
• Auto-fire stops
• Charge meter fills on screen
• High risk, high reward

💥 RELEASE (After charging)

• Fire charged shot (2 damage + expanding shockwave for 1 AOE damage)
• Reverse at 400% speed for 0.2 seconds (12 frames)
• Your dramatic escape move

⚠️ BURNOUT (Hold charge too long)

• If you stay charged for 1 seconds (60 frames) without releasing, you overheat
• Speed drops to burnout mode (2.0x, faster than charging but slower than normal)
• Cannot shoot for 1 second (60 frames) cooldown
• Visual warning: flashing sprite

Enemy Waves

• Popcorn Enemies - Float in formation, shoot periodically (1 HP)
• Kamikaze Divers - Telegraph their attack before diving at you (2 HP)
• Reflect Barriers - Bounce bullets back at you (3 HP, preserves bullet damage)
• Absorb Barriers - Catch up to 3 bullets, then spit them back (1 HP)
• Elite Variants - Tougher versions with more HP (2-5 HP), faster shooting
• Boss Encounter - Multi-phase battle at wave 10

Combat:

• 3 lives to start (bonus health drops from enemies!)
• Auto-fire every 0.5 seconds (30 frames)
• Regular shots: fast (3 pixels/frame), 1 damage
• Charged shots: slower (2 pixels/frame), 2 damage direct + 1 damage shockwave (20 pixel radius)

Combo System:

• Each successful bullet hit increases combo counter
• Missing (bullet flies off-screen) breaks combo and awards bonus points
• Combo multiplier increases exponentially with streak length
• Breaking long combos awards massive score bonuses
• Combo record tracks your best unbroken chain
• Visual counter displays current combo in real-time

Wave Clear Bonus:

• Clearing waves quickly awards time bonus points
• Bonus scales inversely with clear time (faster = higher bonus)
• Perfect clears (no damage taken) multiply the time bonus
• Displayed at wave completion screen

Power-Up Bullets:

• Rapid Fire: 3.75x faster fire rate, smaller bullets for 5 seconds (300 frames)
• Pierce: Faster bullets pass through 2 enemies for 4 seconds (240 frames)
• Rapid + Pierce: Stack both for fast-firing piercing devastation

Barrier Mechanics:

• Reflect Barriers instantly reverse bullet direction, keeping damage/type
• Absorb Barriers store up to 3 bullets, release all at once after 1.5 seconds (90 frames)
• Charged shockwaves damage barriers in blast radius
• Reflected bullets retain full power - your 2-damage charged shot comes back at 2 damage

Power-Ups

Enemies drop helpful items when destroyed:

• ❤️ Health - Restore 1 life (up to max 3)
• ⚡ Rapid Fire - 50% faster fire rate (8 frames), smaller bullets, lasts 5 seconds (300 frames)
• 🔥 Pierce - Shots pass through 2 enemies, increased speed, lasts 4 seconds (240 frames)
• 🛡️ Shield - Absorbs one hit, lasts 6 seconds (360 frames)

Power-ups can stack! Rapid Fire + Pierce creates a devastating bullet stream that tears through formations.

Grab them before they drift off screen!

---

Controls

Gameplay:

• ❎ or Left Mouse Button: Tap/Hold/Release combo

Menu:

• Arrow Keys: Navigate
• 🅾️ / Right Mouse Button: Confirm

---

Strategy Tips

1. Master tapping first - Get comfortable with direction changes before charging
2. Don't overcharge - Release within 2 seconds or face burnout penalty
3. Charge strategically - Find safe windows after clearing enemy clusters
4. Micro-dodge while charging - You're slow (20% speed) but still mobile
5. Time your burst - 400% speed boost lasts only 0.2s, use it wisely
6. Watch dive telegraphs - Kamikazes show warning lines before attacking
7. Use shockwaves on clusters - Charged shots excel against grouped enemies (30px radius)
8. Speed clear for bonuses - Fast wave completion awards extra points
9. Perfect clears multiply bonus - Take no damage to maximize wave clear rewards
10. Maintain combo streaks - Every bullet must hit or your combo breaks
11. Accuracy over speed - Missing one shot costs huge combo bonuses
12. Pierce extends combos - Piercing bullets count multiple hits per shot
13. Strategic combo breaks - Let combo break at peak multiplier for max bonus points
14. Stack power-ups - Rapid Fire + Pierce = formation destroyer
15. Prioritize pierce drops - Passing through enemies multiplies combo potential
16. Beware reflect barriers - Your own bullets become threats, dodge reflected shots
17. Starve absorb barriers - Stop shooting when they're close to releasing (after 3 stored)
18. Prioritize elite enemies - They're tougher (2-5 HP) and shoot faster
19. Learn wave rhythms - Enemies follow predictable spawn patterns
20. Chain transitions - Flow smoothly between tap → charge → release → burst
21. Use audio cues - Sound effects signal state changes and warnings

---

Boss Battles

After 9 normal waves, face a multi-phase boss encounter:

Phase 1: Dropping (~2 seconds)

• Boss spawns enemies below its position
• Drop rate accelerates as boss health decreases
• Enemies appear in "dropper zone" (rows 4-5)

Phase 2: Pause (~2 seconds)

• Blue outer ring indicator
• Brief respite to reposition
• No attacks during pause

Phase 3: Shooting (~2 seconds)

• Red outer ring indicator
• Boss fires aggressive bullet patterns
• No warning telegraphs (instant shots)

Then repeats Phase 1 → 2 → 3 until boss defeated

• Boss health: 50-100 HP (scales with wave number)
• Destroying boss clears all spawned enemies
• Victory screen shows boss defeat stats

---

Inspiration

• Space Invaders - The classic that started it all
• Galaga - Dive-bombing patterns and formation attacks
• Downwell - Single-button depth and commitment mechanics
• Switch 'N' Shoot - Proof that one button can create deep gameplay

---

Technical Details

Engine:

• PICO-8 v0.2.5c fantasy console
• 128x128 resolution at 60 FPS fixed timestep
• 8192 token limit (heavily optimized with Shrinko8)
• Modular source: 10+ Lua files via #include

Architecture:

• Entity-Component-System (eggs.p8 library by @kikito)
• Dual FSM pattern (Player FSM + Input FSM for gesture recognition)
• Combo tracking with multipliers
• Shockwave system with expanding radius (20px) for AOE damage
• Barrier interaction system with bullet reflection/absorption
• Elite enemy variants with enhanced stats (2-5 HP vs 1-2 HP)
• Boss system with 3-phase cycling and dynamic difficulty

Custom DSL Parsers:

• Wave Configuration DSL - Compact text format for enemy formations and spawn patterns
• Enemy Behavior DSL - Script-like syntax for hover patterns, dive trajectories, shooting logic
• Entity Stats DSL - Declarative stat definitions with inheritance and modifiers

These parsers store complex game data efficiently within PICO-8's strict token budget while maintaining readability.

Agent-Driven Development:

• AI Pair Programming - GitHub Copilot + Claude Sonnet 3.5/Opus 4.5 for assisted development
• Custom PICO-8 Prompts - .github/copilot-instructions.md with token optimization rules, ECS patterns, FSM conventions
• Automated Testing - picotestdriver by @kc00l with AI-generated test cases
• Token Budget Validation - MCP (Model Context Protocol) server for real-time token counting
• Code Minification - Shrinko8 web tool for automated token reduction
• Spec-Driven Workflow - ADR (Architecture Decision Records) document design choices
• Headless Testing - pico8 -x cart.p8 for CI/CD validation

AI tools used:

• GitHub Copilot (Claude Sonnet 3.5) - Primary coding assistant with custom PICO-8 instructions
• Claude Sonnet 3.5/Opus 4.5 - Architecture design, documentation, complex refactoring
• MCP PICO-8 Server by @Ebonura - Cart validation, token counting, build automation
• Shrinko8 - Automated code minification and token optimization

Testing:

• picotestdriver test framework by @kc00l
• Integration tests for FSM transitions, input gestures, collision detection
• Headless execution mode for automated validation
• Test suites: player movement, enemy AI, combat mechanics, wave progression

Platform:

• Web browser (HTML export, no installation required)
• PICO-8 desktop player (Windows/Mac/Linux)
• Raspberry Pi compatible
• 128x128 display resolution, 16-color palette

---

Credits

Design & Code: @kc00l
ECS Library: eggs.p8 by @kikito
FSM Library: Custom implementation (initial concept by @kikito, refined by @kc00l)
Test Framework: picotestdriver for automated PICO-8 testing by @kc00l
PICO-8 MCP Server: @Ebonura https://github.com/EBonura/pico8-mcp-server
Shrinko8: Token optimization tool by thisismypassport

---

Version History

v1.3 - Start from any cleared wave!

• added starting wave selection (for completed waves)
• fixed elite shooter enemies behavior (now they correctly shoot at you!)
• reduced elite diver enemies x velocity to make them dodgeable
• added multiplier bonus for wave clear time (which scales with wave numbers)
• invincible player ignores collisions
• unified health bars rendering (boss has a huge embedded bar) => this is to avoid hiding the gift!
• tweaked boss phases durations

v1.2 - Changes all over the place

• changed input scheme (inverted joy/key buttons and added mouse buttons)
• removed endless mode (only 9 waves and a boss now)
• simplified bullet visuals
• changed charge animation
• changed shield visuals
• added powerup durations in the UI
• added victory screen with music
• added boss music

v1.1 - Fixed boss behavior

v1.0 - Initial Release

• Magic Combo system with gesture recognition (tap/hold/release)
• Dual FSM architecture (Player + Input state machines)
• 4 enemy types (hover, diver, reflect barrier, absorb barrier)
• Elite enemy variants with enhanced difficulty
• Boss battles with 3-phase cycling every 10 waves
• Burnout mechanic for overcharging (2s trigger, 1s cooldown)
• Combo system with score multipliers and record tracking
• 4 power-ups (health, rapid fire, pierce, shield)
• Charged shot shockwave mechanics (2 damage direct + 1 damage AOE, 20px radius)
• Barrier interaction mechanics (reflect preserves stats, absorb stores 3 bullets)
• Smooth acceleration between 5 speed states (normal/charging/burst/burnout/reversing)
• Audio/visual feedback (camera shake, SFX, hit flash, charge indicator)
• High score and combo record persistence

---

Feedback Welcome!

Found a bug? Have ideas? Beat a high score?

• Lexaloffle BBS: https://www.lexaloffle.com/bbs/?tid=153604

Share your high scores and speedruns—show us what you can do with one button!