gg-engine-app-development

---

🎨 About

GG-Web-Engine is an open-source framework designed to accelerate the development of web-based 2D/3D applications, including games and simulations. Instead of reinventing the wheel, it integrates seamlessly with powerful libraries like Three.js for rendering and Ammo.js for physics, giving developers complete control over these tools.

Built with flexibility in mind, the engine is designed to work with various tech stacks and allows swapping libraries or creating custom solutions with minimal effort.

🌟 Key Features

• Multi-library Integration: Supports rendering and physics libraries like Three.js, Ammo.js, Pixi.js, Matter.js, and more.
• 2D & 3D Support: Build both 2D and 3D worlds effortlessly.
• Ready-to-use Tools: Includes core functionalities like rendering loops, physics ticks, input handling, and more.
• Serialization & Export: Built-in Blender exporter for 3D geometry and physics properties.
• Entity System: Modular design with reusable entities for rendering, physics, cameras, vehicles, and more.
• Extensible Architecture: Easily integrate or replace components with custom implementations.
• Modern Tech Stack: Written in TypeScript with RxJS for reactive programming.

🔭 Vision

• Provide seamless integrations for existing rendering, physics, and sound libraries.
• Deliver a robust foundation for both 2D and 3D game worlds.
• Empower developers with tools like developer console, cameras, and debug utilities.
• Maintain modularity to ensure maximum flexibility for developers.
• Stay library-agnostic, enabling developers to switch or customize libraries with ease.

🧭 Milestones (Roadmap)

The public roadmap, with per-item status against the current codebase, is available in milestones.md. It's a living proposal, not a contract, and will evolve with community feedback.

🚧 Current Status

Experimental Release

This engine began as part of a project to recreate an old NFS game The Need For Speed Web. Its modular architecture was inspired by the challenges of switching from Cannon.js to Ammo.js and, eventually, to custom reverse-engineered physics engine with minimal changes.

While the current focus is on racing game features and 3D worlds, future updates will expand the engine's versatility. Contributions, feature requests, and bug reports are warmly welcomed!

✨ Features at a Glance

• Physics/Rendering Synchronization: Automates position/rotation updates.
• Customizable Controllers: Add functionality with reusable tick-based controllers.
• Entities: Predefined entities like rigid bodies, triggers, raycast vehicles, and more.
• Character Animation: Bone-animated 3D character models or atlas-framed 2D sprites, with automatic idle/walk/run/crouch/jump (3D) or idle/walk/run/jump (2D) state switching.
• Developer Console: Built-in UI console for debugging and tweaking settings.
• Map Graph Loading: Load map areas dynamically based on proximity (3D worlds).
• Free-Fly Camera: Explore 3D worlds effortlessly.

🔌 Integrations

Note: Current integrations are in early stages and will become more flexible in future releases.

• @gg-web-engine/three - 3D rendering (Three.js)
• @gg-web-engine/ammo - 3D physics (Ammo.js)
• @gg-web-engine/rapier3d - 3D physics (Rapier.js)
• @gg-web-engine/pixi - 2D rendering (Pixi.js)
• @gg-web-engine/matter - 2D physics (Matter.js)
• @gg-web-engine/rapier2d - 2D physics (Rapier.js)
• @gg-web-engine/audio - 2D/3D positional audio (Web Audio API)

⚡ Quickstart

Installation

1. Install the core package:

npm install --save @gg-web-engine/core

1. Install integration modules. For example, to use Three.js and Ammo.js:

npm install --save @gg-web-engine/three @gg-web-engine/ammo

Usage:

1. add somewhere in dom tree: <canvas id="gg"></canvas>
2. remove default margin from page via CSS: body { margin: 0; }
3. write bootstrap script, example:

import { Gg3dWorld, Pnt3, Qtrn } from '@gg-web-engine/core';
import { ThreeSceneComponent } from '@gg-web-engine/three';
import { AmmoWorldComponent } from '@gg-web-engine/ammo';

// create world
const world = new Gg3dWorld({
  visualScene: new ThreeSceneComponent(),
  physicsWorld: new AmmoWorldComponent(),
});
await world.init();

// create viewport and renderer
const renderer = world.addRenderer(
  world.visualScene.factory.createPerspectiveCamera(),
  document.getElementById('gg')! as HTMLCanvasElement
);
renderer.position = { x: 12, y: 12, z: 12 };
renderer.rotation = Qtrn.lookAt(renderer.camera.position, Pnt3.O);

// create floor (static rigid body)
world.addPrimitiveRigidBody({
  shape: { shape: 'BOX', dimensions: { x: 7, y: 7, z: 1 } },
  body: { bodyType: 'static' },
});

// spawn cubes with mass 1kg twice a second
const spawnTimer = world.createClock(true);
spawnTimer.tickRateLimit = 2;
spawnTimer.tick$.subscribe(() => {
  // generate cube
  let item = world.addPrimitiveRigidBody({
    shape: { shape: 'BOX', dimensions: { x: 1, y: 1, z: 1 } },
    body: { mass: 1 },
  });
  // set position to cube
  item.position = { x: Math.random() * 5 - 2.5, y: Math.random() * 5 - 2.5, z: 10 };
  // delete cube from world after 30 seconds
  setTimeout(() => { world.removeEntity(item, true); }, 30000);
});

// start simulation
world.start();

And run it:

🤖 Building your app with an AI coding agent

This repo ships a Claude Code skill, gg-engine-app-development, that teaches an agent the engine's mental model (worlds, entities, visual/physics components), the bootstrap pattern above, available shapes/controllers/loaders, and common pitfalls — so it writes correct GG-Web-Engine code instead of guessing from the README alone.

Install it into your own app's repo with npx skills:

npx skills add AndyGura/gg-web-engine --skill gg-engine-app-development -y

Then just ask your agent to build your scene/game — Claude Code picks the skill up automatically once it's under .claude/skills/. The other skills in this repo ([