Interactive demos for the Blit-Tech WebGPU retro game engine.

This repository showcases the capabilities of Blit-Tech through 8 interactive demos, demonstrating everything from basic rendering to advanced sprite effects.

• Node.js v20 or higher (LTS)
• pnpm v10.24.0 or higher
• A WebGPU-compatible browser:
  • Chrome/Edge 113+ (Windows, macOS, Linux, Android)
  • Firefox Nightly (with dom.webgpu.enabled in about:config)
  • Safari 18+ (macOS/iOS)

This project depends on the Blit-Tech library using a pnpm workspace. Since Blit-Tech is not yet published to npm, you need to set up a local workspace structure.

Detailed Setup Guide: See docs/EXTERNAL-DEVELOPER-SETUP.md for complete step-by-step instructions and troubleshooting.

# 1. Create workspace directory
mkdir blit-tech-workspace && cd blit-tech-workspace

# 2. Clone both repositories
git clone https://github.com/vancura/blit-tech.git
git clone https://github.com/vancura/blit-tech-demos.git

# 3. Create workspace config
cat > pnpm-workspace.yaml << 'EOF'
packages:
  - "blit-tech"
  - "blit-tech-demos"
EOF

# 4. Install dependencies
pnpm install

Your directory structure:

blit-tech-workspace/          # Your workspace root
├── pnpm-workspace.yaml       # Workspace config (you created this)
├── blit-tech/                # Cloned from GitHub
└── blit-tech-demos/          # Cloned from GitHub

Note: Once Blit-Tech is published to npm, you'll be able to install it directly without this workspace setup.

Start the development server:

cd blit-tech-demos
pnpm dev

The browser will open automatically at http://localhost:5173/demos/ showing the demo gallery.

For seamless development where changes to the Blit-Tech library automatically rebuild:

cd blit-tech-demos
pnpm dev:watch

This runs both the library watcher and the dev server concurrently. Any changes to Blit-Tech source files will trigger an automatic rebuild.

Minimal game setup and game loop

Demonstrates the fundamental structure of a Blit-Tech game:

• Hardware configuration (queryHardware)
• Game initialization
• Update/render loop separation
• Basic primitive drawing
• Automatic bouncing square movement

Key Concepts: Game lifecycle, fixed timestep, primitive drawing

Drawing pixels, lines, and rectangles

Showcases all available primitive drawing functions:

• Individual pixel drawing
• Line rendering (Bresenham algorithm)
• Rectangle outlines
• Filled rectangles
• Screen clearing

Key Concepts: Coordinate system, color manipulation, primitive API

Scrolling world with camera offsets

Advanced camera system demonstration:

• World scrolling with camera offset
• Multiple viewport layers
• Mini-map implementation
• UI overlay (unaffected by camera)
• Performance-optimized rendering

Key Concepts: Camera transforms, viewport management, layered rendering

Mathematical animations and effects

Generative art and mathematical patterns:

• Spiral patterns
• Wave animations
• Lissajous curves
• Parametric equations
• Performance-optimized rendering

Key Concepts: Procedural generation, mathematics in games, optimization

Sprite sheets and texture rendering

Core sprite rendering features:

• Loading sprite sheets
• Drawing sprites with source rectangles
• Color tinting
• Transparency
• Texture batching

Key Concepts: Asset loading, sprite sheets, texture rendering

Tick-based timing and state machines

Game timing and animation systems:

• Tick counter usage
• Frame-based animation
• State machines
• Cooldown timers
• Animation cycling

Key Concepts: Game timing, state management, animation logic

Color tinting and visual effects

Practical sprite effect techniques:

• Damage flash effect
• Drop shadows
• Team color tinting
• Ambient lighting
• Effect combinations

Key Concepts: Visual feedback, color manipulation, game feel

Bitmap font rendering

Text rendering system:

• Bitmap font loading
• Text rendering with colors
• Variable-width fonts
• Custom font support
• Font attribution

Key Concepts: Text rendering, bitmap fonts, UI elements

Recommended order for learning:

1. basics.ts - Start here to understand core concepts
2. primitives.ts - Learn the drawing API
3. fonts.ts - Add text rendering
4. sprites.ts - Work with sprite sheets
5. sprite-effects.ts - Apply visual effects
6. animation.ts - Implement timing and state
7. patterns.ts - Explore procedural techniques
8. camera.ts - Master advanced camera systems

blit-tech-demos/
├── demos/                    # All HTML files
│   ├── index.html            # Demo gallery
│   ├── basics.html
│   ├── primitives.html
│   ├── camera.html
│   ├── patterns.html
│   ├── sprites.html
│   ├── animation.html
│   ├── sprite-effects.html
│   ├── fonts.html
│   └── styles.css           # Demo styling
├── src/                      # Demo TypeScript files
│   ├── basics.ts
│   ├── primitives.ts
│   ├── camera.ts
│   ├── patterns.ts
│   ├── sprites.ts
│   ├── animation.ts
│   ├── sprite-effects.ts
│   └── fonts.ts
├── public/                   # Static assets
│   └── fonts/                # Bitmap fonts
├── _partials/                # Handlebars templates
│   ├── layout-top.hbs
│   ├── layout-bottom.hbs
│   ├── font-attribution.hbs
│   └── plausible-analytics.hbs
├── _config/
│   └── contexts.ts           # Page context data
├── .github/workflows/        # CI/CD workflows
│   └── deploy.yml           # Cloudflare Pages deployment
├── package.json
├── vite.config.ts
├── tsconfig.json
└── README.md

pnpm build

Builds all demos to the dist/ directory.

pnpm preview

pnpm lint          # Run ESLint
pnpm format        # Format code with Biome + Prettier
pnpm typecheck     # TypeScript type checking

These demos currently use the local Blit-Tech library via pnpm workspace (see Setup section above). This workspace setup is required because Blit-Tech is not yet published to npm.

When Blit-Tech is published to npm, you'll be able to install it directly:

npm install blit-tech
# or
pnpm add blit-tech

Then import in your project:

import { BT, bootstrap, Color32, Vector2i, type IBlitTechGame } from 'blit-tech';

No workspace setup will be needed once the package is on npm.

The demos are automatically deployed to Cloudflare Pages when changes are pushed to the main branch. The deployment process is handled by GitHub Actions:

1. Build in GitHub Actions: The blit-tech library is cloned, built, and then the demos are built against it
2. Deploy Artifacts: The built dist/ directory is deployed to Cloudflare Pages using the cloudflare/pages-action
3. Skip Cloudflare Build: Cloudflare Pages is configured to skip its own build process via wrangler.jsonc and .cfignore

• Development: URLs include the demos/ path (e.g., http://localhost:5173/demos/basics.html)
• Production: URLs are at the root (e.g., https://blit-tech-demos.ambilab.com/basics.html)

A custom Vite plugin flattens the dist/demos/ output to dist/ during the build, providing cleaner production URLs while keeping source files organized in the demos/ folder.

• vite.config.ts: Contains flattenDemosPlugin() to restructure build output for production
• wrangler.jsonc: Specifies pages_build_output_dir to indicate pre-built content
• .cfignore: Prevents Cloudflare from attempting to install dependencies
• GitHub Actions: Handles all build steps with proper pnpm workspace setup

This approach works around Cloudflare Pages' lack of native pnpm workspace support while maintaining the ability to use the local unpublished blit-tech dependency.

ISC

• Blit-Tech on GitHub: github.com/vancura/blit-tech
• Live Demos: blit-tech-demos.ambilab.com