@gamebyte/framework

v1.3.0

Published

8 days ago

A comprehensive JavaScript game engine framework that unifies 2D and 3D game development with Laravel-inspired architecture

Downloads

179

0High
0Medium
0Low

canerdogan

game-engine javascript typescript pixi.js three.js mobile-games 2d 3d framework tree-shaking

🎮 GameByte Framework

Modern Mobile-First Game Development Framework

A comprehensive JavaScript game framework that unifies 2D and 3D game development with Laravel-inspired architecture.

✨ View Live Demos • 📖 Quick Start • 🎨 UI Components

✨ Features

🎨 Modern UI System - Beautiful components with gradients, glow, shadows, animations
🔄 Reactive State - Vue/Svelte-inspired state management with auto-updates
🚀 Laravel Architecture - Service providers, dependency injection, facades
🎬 Scene Management - Smooth transitions & lifecycle management
⚡ Physics Integration - Matter.js (2D) & Cannon.js (3D)
🔊 Audio System - Spatial audio, music, SFX with mobile optimization
📱 Mobile-First - 44px touch targets, performance optimizations
🎯 TypeScript - 100% type safety
🎮 Dual Rendering - Pixi.js v8 (2D) & Three.js (3D)

🚀 Quick Start

Installation

npm install gamebyte-framework

Basic 2D Game

import { createGame } from 'gamebyte-framework';
import * as PIXI from 'pixi.js';

// Create and initialize
const game = createGame();
const canvas = document.createElement('canvas');
canvas.width = 800;
canvas.height = 600;
document.body.appendChild(canvas);

await game.initialize(canvas, '2d');

// Get services
const renderer = game.make('renderer');
const sceneManager = game.make('scene.manager');

// Start game loop
game.start();

UMD Build (Browser)

<!DOCTYPE html>
<html>
<head>
    <title>My Game</title>
</head>
<body>
    <!-- Load Pixi.js from CDN -->
    <script src="https://cdn.jsdelivr.net/npm/pixi.js@8/dist/pixi.min.js"></script>

    <!-- Load GameByte -->
    <script src="./dist/gamebyte.umd.js"></script>

    <script>
        const game = GameByteFramework.createGame();
        // Your game code...
    </script>
</body>
</html>

🤖 For AI Agents & Code Assistants

GameByte is optimized for AI-driven development with tiered documentation and discoverable patterns.

Quick Start for Agents

1. Load Core Knowledge (Required)

Read: docs/agent-guide/CORE_API.md (~2000 tokens)
Cheatsheet: docs/agent-guide/QUICK_REFERENCE.md (~500 tokens)

2. Discover Advanced Topics (As Needed)

# Search guides by keyword
grep -r "physics" docs/guides/
grep -r "mobile.*optimization" docs/guides/

3. Reference Working Examples

Platformer: examples/platformer/
UI Components: examples/ui-showcase/

Documentation Tiers

| Tier | Content | When to Load | |------|---------|--------------| | Tier 1 | Core API (~2000 tokens) | Always (pre-loaded) | | Tier 2 | Advanced guides | On-demand (grep/semantic search) | | Tier 3 | Working examples | For patterns/templates |

Key Features for AI

Minimal context - Core API is ~2000 tokens
Smart defaults - 40+ auto-configured settings
Discoverable - Keyword-enriched markdown for grep
Type-rich - JSDoc examples for autocomplete
4-line games - createGame() → initialize() → start()

Integration with RAG Systems

All markdown docs include semantic keywords for vector search:

<!-- keywords: physics, collision, 2d, 3d, matter, cannon -->

🎨 UI Components

Modern Button

import { UIButton } from 'gamebyte-framework';

const button = new UIButton({
    text: 'PLAY',
    width: 200,
    height: 60,
    backgroundColor: 0x4CAF50,
    gradient: { enabled: true, colorTop: 0x66BB6A, colorBottom: 0x388E3C },
    glowEffect: true,
    shadowEffect: true,
    rippleEffect: true
});

button.on('click', () => console.log('Clicked!'));
scene.addChild(button.getContainer());

TopBar with Resources

import { TopBar, TopBarItemType } from 'gamebyte-framework';

const topBar = new TopBar({
    width: 800,
    items: [
        {
            id: 'coins',
            type: TopBarItemType.RESOURCE,
            icon: coinTexture,
            value: 1000,
            format: 'abbreviate', // "1K"
            animated: true
        },
        {
            id: 'timer',
            type: TopBarItemType.TIMER,
            value: 60,
            format: 'time' // "1:00"
        }
    ]
});

scene.addChild(topBar.getContainer());
topBar.updateItem('coins', 1500, true);

🎬 Scene Management

import { BaseScene } from 'gamebyte-framework';

class MyScene extends BaseScene {
    constructor() {
        super('my-scene', 'My Scene');
    }

    async initialize() {
        await super.initialize();
        // Setup your scene
    }

    update(deltaTime: number) {
        super.update(deltaTime);
        // Update game logic
    }
}

// Add and switch scenes
const scene = new MyScene();
sceneManager.add(scene);
await sceneManager.switchTo('my-scene', {
    type: 'fade',
    duration: 500
});

🏗️ Architecture

Service Container

// Bind services
game.bind('my.service', () => new MyService());
game.singleton('global.service', () => new GlobalService());

// Resolve services
const service = game.make('my.service');

Service Providers

import { AbstractServiceProvider } from 'gamebyte-framework';

export class MyServiceProvider extends AbstractServiceProvider {
    register(app: GameByte): void {
        app.singleton('my.feature', () => new MyFeature());
    }
}

game.register(new MyServiceProvider());

Facades

import { Renderer, Scenes, UI, Audio } from 'gamebyte-framework';

Renderer.start();
await Scenes.switchTo('game');
const button = UI.createButton({...});
Audio.playMusic('background');

🔄 Reactive State Management

Vue/Svelte-inspired reactive state system for automatic UI updates.

import { createState } from 'gamebyte-framework';

// Create reactive game state
const gameState = createState({
  score: 0,
  health: 100,
  level: 1
});

// Direct property access - UI auto-updates
gameState.score += 100;

// Subscribe to changes
const unsubscribe = gameState.on('score', (newVal, oldVal) => {
  console.log(`Score: ${oldVal} → ${newVal}`);
});

// Batch updates (single notification)
gameState.batch(state => {
  state.score += 50;
  state.health -= 10;
});

// Reset to initial values
gameState.reset();

// Get plain object snapshot
const snapshot = gameState.value;

Computed Values

import { createState, computed } from 'gamebyte-framework';

const state = createState({ base: 10, bonus: 5 });
const total = computed(() => state.base + state.bonus);

console.log(total.value); // 15
state.bonus = 10;
console.log(total.value); // 20

🎮 Core Systems

Physics

import { Physics } from 'gamebyte-framework';

// 2D Physics (Matter.js)
Physics.create2DWorld({ gravity: { x: 0, y: 1 } });
const body = Physics.createBody({ x: 100, y: 100, width: 50, height: 50 });

// 3D Physics (Cannon.js)
Physics.create3DWorld({ gravity: { x: 0, y: -9.8, z: 0 } });

Audio

import { Music, SFX, Spatial } from 'gamebyte-framework';

Music.play('background', { loop: true, volume: 0.7 });
SFX.play('click');
Spatial.play('explosion', { position: { x: 10, y: 0, z: 5 } });

Input

import { Input } from 'gamebyte-framework';

Input.keyboard.on('KeyW', () => console.log('W pressed'));
Input.touch.on('tap', (e) => console.log('Tapped at:', e.x, e.y));
Input.gamepad.on('button-a', () => console.log('A pressed'));

Assets

import { Assets } from 'gamebyte-framework';

await Assets.load([
    { key: 'player', url: 'player.png', type: 'texture' },
    { key: 'music', url: 'music.mp3', type: 'audio' }
]);

const texture = Assets.get('player');

🌐 3D Rendering

GameByte supports 3D rendering with Three.js:

UMD Build: Use direct Three.js API (see docs/guides/rendering-3d-setup.md)
ESM/CJS: Import ThreeRenderer and BaseScene3D directly

// ESM/CJS approach
import { createGame } from 'gamebyte-framework';
import * as THREE from 'three';

const game = createGame();
await game.initialize(canvas, '3d');

// Use Three.js API directly for 3D scenes
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
// ... rest of Three.js setup

📖 Full 3D Rendering Guide →

📁 Project Structure

gamebyte-framework/
├── src/
│   ├── core/              # Framework core
│   ├── rendering/         # 2D/3D renderers
│   ├── ui/                # UI components
│   ├── scenes/            # Scene management
│   ├── physics/           # Physics engines
│   ├── audio/             # Audio system
│   ├── input/             # Input handling
│   ├── assets/            # Asset management
│   ├── services/          # Service providers
│   ├── facades/           # Static facades
│   └── index.ts           # Main entry
├── dist/
│   ├── index.js           # ES module
│   ├── index.cjs.js       # CommonJS
│   ├── gamebyte.umd.js    # UMD bundle (2D only)
│   └── renderers/
│       └── three3d.js     # 3D renderer bundle
├── docs/
│   └── guides/
│       └── rendering-3d-setup.md
├── index.html             # Demo hub
├── test-*.html            # Demo pages
└── README.md

🎓 Live Demos

All demos are available in the docs-site/static/demos/ directory:

Demo Index - All demos in one place
Platformer Game - Complete hyper-casual platformer
Space Shooter - Arcade shooter with particles
Breakout - Classic brick breaker
Memory Game - Card matching game
Snake - Classic snake game
UI Showcase - UI component gallery

🛠️ Development

# Install dependencies
npm install

# Build framework
npm run build

# Development mode (watch)
npm run dev

# Run tests
npm test

# Start demo server
npx http-server -p 8080

📚 Documentation

📖 3D Rendering Guide - Complete 3D setup guide
📝 Changelog - Version history
🤝 Contributing - Contribution guidelines
🗺️ Roadmap - Development roadmap

🎯 Roadmap

✅ v1.0 - Core Framework (Complete)

✅ Service container & providers
✅ 2D rendering (Pixi.js v8)
✅ 3D rendering (Three.js)
✅ Scene management
✅ Modern UI components (15+ components)
✅ Physics (Matter.js, Cannon.js)
✅ Audio system
✅ Input handling
✅ Asset management

✅ v1.1 - Enhanced UI & State (Complete)

✅ Reactive state management (Vue/Svelte-inspired)
✅ Game-specific components (HexagonButton, MergeGrid, TopBar)
✅ Celebration effects (Confetti, Shimmer, Starburst)
✅ GameStyle buttons (Candy Crush/Brawl Stars style)
✅ Modal panels & bottom sheets

🚧 v1.2 - Game Boilerplates (In Progress)

Hyper-casual game templates
Puzzle game mechanics
Idle/clicker systems
Match-3 mechanics

📋 v2.0 - Tools & Services (Planned)

Visual level editor
Analytics integration
Cloud save system
A/B testing framework

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Credits

Built on amazing open-source libraries:

Pixi.js - 2D rendering
Three.js - 3D rendering
Matter.js - 2D physics
Cannon.js - 3D physics

Inspired by Laravel Framework architecture.

Built with ❤️ for Game Developers

⭐ Star us on GitHub — it helps!

Live Demos • Quick Start • Documentation