4cecoder / kap

A dead simple 2D game engine for browsers with a visual editor

Kap - Dead Simple 2D Game Engine

A beginner-friendly 2D game engine for browsers with a visual editor. No build step required - just pure ES modules!

🚀 Quick Start

1. Run the visual editor:

   bun run dev
   # or just open index.html in your browser

2. Try the examples:

   • examples/games/platformer/ - Full platformer game
   • examples/games/vanilla/ - Vanilla game loop example
   • examples/demos/ - Simple demo

📁 Project Structure

kap/
├── src/                    # Source code
│   ├── core/              # Core engine systems
│   │   ├── engine.js      # Scene management
│   │   ├── renderer.js    # Canvas rendering
│   │   ├── input.js       # Input handling
│   │   ├── assets.js      # Asset loading
│   │   └── utils.js       # Utility functions
│   ├── systems/           # Game systems
│   │   ├── sprite.js      # Sprite animation
│   │   ├── tilemap.js     # Tile-based maps
│   │   ├── physics.js     # Physics system
│   │   └── entity.js      # Entity management
│   ├── engine/            # Simplified API
│   │   └── index.js       # Main engine entry point
│   ├── editor/            # Visual editor
│   │   └── index.js       # Editor interface
│   └── game/              # Game-specific code
│       ├── index.js       # Game entry point
│       ├── scenes.js      # Scene definitions
│       ├── player.js      # Player logic
│       └── level.js       # Level/tilemap setup
├── examples/              # Example projects
│   ├── games/            # Complete games
│   │   ├── platformer/   # Platformer example
│   │   └── vanilla/      # Vanilla game loop
│   ├── demos/            # Simple demos
│   └── templates/        # Code templates
├── assets/               # Game assets
│   ├── images/          # Sprites and images
│   ├── audio/           # Sound effects and music
│   └── fonts/           # Custom fonts
├── docs/                # Documentation
├── tests/               # Test files
└── config/              # Configuration files

🎮 API Reference

Simple API (for beginners)

import { setBackground, addPlatform, addPlayer, movePlayer, jumpPlayer, onKey, engine } from './src/engine/index.js'

// Set up your game
setBackground('#87ceeb')
addPlatform(0, 448, 640, 32, '#228B22')
addPlayer(64, 416, 32, 32, 'player.png')

// Add controls
onKey('ArrowLeft', () => movePlayer(-120, 0))
onKey('ArrowRight', () => movePlayer(120, 0))
onKey(' ', () => jumpPlayer())

// Start the game
engine.start('game')

Advanced API (for developers)

import { Engine } from './src/core/engine.js'
import { Renderer } from './src/core/renderer.js'
import { Input } from './src/core/input.js'
import { Assets } from './src/core/assets.js'
import { Sprite } from './src/systems/sprite.js'

// Create engine instances
const canvas = document.getElementById('game')
const engine = new Engine()
const renderer = new Renderer(canvas)
const input = new Input()
const assets = new Assets()

// Define scenes
engine.addScene('game', (dt) => {
    renderer.clear('#87ceeb')
    // Your game logic here
})

// Start the engine
engine.start('game')

🎨 Visual Editor

The visual editor provides:

• Drag & Drop: Place objects visually
• Property Panel: Edit object properties
• Grid System: Snap to grid for precision
• Templates: Quick-start templates
• Export: Generate standalone HTML files
• Undo/Redo: Full history support

🛠️ Development

Prerequisites

• Bun (recommended) or any modern browser
• No build tools required!

Running Examples

# Start development server
bun run dev

# Or open examples directly in browser:
open examples/games/platformer/index.html
open examples/games/vanilla/index.html
open examples/demos/index.html

Code Style

• Use ES modules (import/export)
• 2 or 4 spaces for indentation (be consistent)
• No semicolons required
• Use camelCase for variables/functions
• Use PascalCase for classes

📚 Examples

Platformer Game

A complete platformer with:

• Player movement and jumping
• Tile-based collision
• Sprite animation
• Multiple scenes (menu, game, gameover)

Vanilla Game Loop

Shows how to build a game without the engine:

• Custom game loop
• Manual collision detection
• Direct canvas rendering

Visual Editor Demo

Interactive editor with:

• Drag & drop object placement
• Real-time property editing
• Code generation and export

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with bun run dev
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built for educational purposes
• Inspired by classic 2D game engines
• Designed to be approachable for beginners