sg.js API Reference

Complete reference for the SiliconGhetto engine JavaScript API (sg.js).

import sg from 'https://cdn.siliconghetto.com/engine/v0.1/sg.js';

Lifecycle

sg.init(canvasId, width, height) — async

Initialize the engine. Loads the WASM module, selects hardware WebGPU by default, falls back to WebGL2 only when needed, and sets up the rendering context.

await sg.init('game-canvas', 800, 600);

sg.run({ update, draw })

Start the game loop. update() runs on the engine tick for game logic. draw() runs after for rendering.

sg.run({
    update() { /* game logic */ },
    draw() { /* rendering */ },
});

sg.stop()

Stop the game loop.

sg.clear(r, g, b)

Set the background clear color. Call at the start of draw().

sg.clear(0.1, 0.1, 0.2); // dark blue

Time

Input

Keyboard

Key names use KeyboardEvent.code values: 'KeyW', 'ArrowUp', 'Space', 'ShiftLeft', etc.

if (sg.keyDown('KeyW')) { /* moving forward */ }
if (sg.keyPressed('Space')) { /* just jumped */ }

Mouse

Entities (2D)

sg.spawn(opts) → number

Create an entity. Returns a numeric handle used to reference the entity in all other calls.

const player = sg.spawn({
    x: 400, y: 300,
    sprite: { w: 32, h: 32, r: 1, g: 0.3, b: 0.3 },
    collision: { w: 32, h: 32 },
    tag: 'player',
});

sg.despawn(entity)

Remove an entity and clean up all subsystem state (health, physics, AI, animation).

Position & Velocity

Appearance

Tags

Camera

Drawing

Call these inside draw(). All coordinates are screen-space pixels.

sg.drawRect(10, 10, 200, 30, { r: 0, g: 0, b: 0, a: 0.5 });
sg.drawText('Score: 100', 15, 15, 14, { r: 1, g: 1, b: 1 });

Screen

Physics (2D)

Collision Detection

Platformer Physics

Full platformer controller with gravity, jumping (coyote time + jump buffer), and variable jump height.

const player = sg.spawn({ x: 100, y: 100, collision: { w: 16, h: 24 } });
sg.setPlatformerPhysics(player, {
    gravity: 980, jumpForce: 400, maxFall: 600, speed: 200,
    coyoteTime: 0.1, jumpBufferTime: 0.1,
});

// In update():
const input = sg.keyDown('ArrowRight') ? 1 : sg.keyDown('ArrowLeft') ? -1 : 0;
if (sg.keyPressed('Space')) sg.platformerJump(player);
sg.platformerJumpHeld(player, sg.keyDown('Space'));

const { dx, dy } = sg.updatePlatformer(player, input);
const { hitX, hitY } = sg.tilemapCollide(sg.getX(player), sg.getY(player), 8, 12, dx, dy);
sg.platformerResolve(player, hitX, hitY, dy > 0);

Top-Down Physics

sg.setTopDownPhysics(entity, { speed: 150, friction: 600 });

Tile Maps

Grid-based level system with collision.

sg.createTileMap(20, 15, 32); // 20x15 grid, 32px tiles
sg.setTile(5, 14, 1);         // solid ground
sg.setTileFlags(3, 10, 2, 2); // platform (one-way)

// In draw():
sg.drawTileMap();

Animation

Frame-based sprite animation system.

sg.addAnimation(player, 'run', { frames: [0, 1, 2, 3], fps: 10, loop: true });
sg.addAnimation(player, 'idle', { frames: [0], fps: 1 });
sg.playAnim(player, 'run');

// In draw():
const frame = sg.getAnimFrame(player); // current frame index

Health & Damage

sg.setHealth(enemy, 50);        // 50 HP
sg.damage(enemy, 20);           // -20 HP, triggers invincibility
sg.heal(enemy, 10);             // +10 HP (capped at max)

if (sg.isDead(enemy)) sg.despawn(enemy);

Projectiles

const bullet = sg.spawnProjectile(x, y, 1, 0, 300, {
    damage: 25, lifetime: 2, owner: player,
    w: 8, h: 4, r: 1, g: 0.8, b: 0,
});

// In update():
sg.updateProjectiles();
for (const { handle, damage } of sg.checkProjectileHits()) {
    sg.damage(handle, damage);
}

// In draw():
sg.drawProjectiles();

AI Behaviors

sg.setAI(enemy, 'chase', { target: player, speed: 80 });
sg.setAI(guard, 'patrol', { points: [[100,200], [300,200]], speed: 60 });
sg.setAI(rabbit, 'flee', { target: player, speed: 120, maxDistance: 200 });

// In update():
for (const { handle, dx, dy, facing } of sg.updateAI()) {
    const { hitX, hitY } = sg.tilemapCollide(sg.getX(handle), sg.getY(handle), 8, 12, dx, dy);
    sg.setPos(handle, sg.getX(handle) + (hitX ? 0 : dx), sg.getY(handle) + (hitY ? 0 : dy));
}

2D Spatial Index

Fast broadphase queries for busy 2D games with many actors, pickups, hitboxes, or sensors.

const spatial = sg.createSpatialIndex({ cellSize: 64 });

spatial.insert({ entity: player, x: sg.getX(player), y: sg.getY(player), w: 18, h: 28 });
for (const enemy of enemies) {
    spatial.insert({ entity: enemy, x: sg.getX(enemy), y: sg.getY(enemy), w: 24, h: 24 });
}

const nearby = spatial.queryRadius(sg.getX(player), sg.getY(player), 160);
const hit = spatial.raycast(sg.getX(player), sg.getY(player), sg.mouseX, sg.mouseY, [player]);
for (const { a, b } of spatial.pairs()) {
    // Run exact gameplay collision only for nearby overlapping candidates.
}

Kinematic Controller

const solids = sg.createSpatialIndex({ cellSize: 64 });
const playerBody = sg.createKinematicController2D({
    entity: player,
    spatial: solids,
    x: sg.getX(player),
    y: sg.getY(player),
    w: 18,
    h: 28,
});

const move = playerBody.move(inputX * speed * sg.dt, velocityY * sg.dt);
sg.setPos(player, move.x, move.y);
if (move.grounded) velocityY = 0;

Platform Composition

sg.createGame(opts) — async

Primary entry point for new games. It composes runtime options, world setup, content packs, and capability declarations.

const game = await sg.createGame({
    runtime: {
        tickRate: 60,
        deterministic: true,
        saveProfile: 'sg.save.v2',
    },
    world: {
        canvas: 'game-canvas',
        topology: 'chunked-grid-3d',
        streaming: 'player-centric',
        seed: 42,
    },
    packs: ['sg.survival@0.1.0'],
    capabilities: ['inventory', 'crafting', 'procedural_world'],
});

sg.registeredPacks()

Returns first-party pack metadata for composition tooling:

const [{ id, version, capabilities }] = sg.registeredPacks();

Returns { seed, canvas, width, height, runtime, world, packs, capabilities, composition, template, game }. composition.bootMode is 'base-runtime' for a base world and 'pack-template' when a first-party pack boots through a pack template.

Block Worlds

Quick Start

const { seed } = await sg.createGame({
    world: {
        canvas: 'game-canvas',
        worldHeight: 64,
        seed: 42,
    },
});

sg.run({
    update() { sg.fpsUpdate(); },
    draw() { sg.clear(0.5, 0.7, 1.0); },
});

sg.createGame(opts) — async

Platform setup: initializes engine, creates a voxel world, generates biome-driven terrain, enables FPS controller, and sets up pointer lock.

Returns { seed, canvas, width, height }.

Block Operations

Block Types

Access via sg.BLOCKS or sg.blockTypes:

sg.setBlock(x, y, z, sg.BLOCKS.STONE);
sg.setBlock(x, y, z, sg.BLOCKS.DIAMOND_ORE);

Block names are available via sg.BLOCK_NAMES[id].

FPS Controller

Enabled automatically by createGame(), or manually:

sg.enableFPSController({
    speed: 7,             // walk speed
    jumpForce: 8.5,       // jump velocity
    gravity: 22,          // gravity strength
    sensitivity: 0.003,   // mouse look sensitivity
    flySpeed: 14,         // fly mode speed
    sprintMultiplier: 1.6,// shift sprint
    playerRadius: 0.28,   // collision cylinder radius
    playerHeight: 1.65,   // collision cylinder height
});

Built-in controls: WASD (move), Mouse (look), Space (jump), Shift (sprint), F (fly toggle), Ctrl (fly down).

Raycasting

DDA (Digital Differential Analyzer) — exact, never misses a block.

// From FPS eye position:
const hit = sg.voxelRaycast(7);
if (hit.hit) {
    // hit.x, hit.y, hit.z — the block that was hit
    // hit.prevX, hit.prevY, hit.prevZ — the air block before it (for placing)
    // hit.blockType — block type ID
}

// From arbitrary position + direction:
const hit2 = sg.voxelRaycastFrom(ox, oy, oz, dx, dy, dz, 20);

Collision

Terrain Generation

sg.generateTerrain({ seed: 42 });

Generates terrain using simplex noise with biome-driven terrain, cave systems, Y-level ore distribution, biome-specific trees, and surface decoration.

Biome System

Default biomes are registered automatically. To customize:

// Replace all biomes with custom set:
sg.resetBiomes();
sg.addBiome({
    name: 'Alien Desert',
    tempRange: [0.5, 1.0],
    moistRange: [-1, 0],
    surface: sg.BLOCKS.RED_SAND,
    subSurface: sg.BLOCKS.TERRACOTTA,
    treeDensity: 0.02,
    treeTrunk: sg.BLOCKS.CACTUS,
    treeLeaves: sg.BLOCKS.AIR,
});
sg.generateTerrain({ seed: 42 });

Assets

await sg.loadTexture('hero', 'hero.png');
await sg.loadSound('jump', 'jump.wav');

sg.drawSprite('hero', 100, 200, 32, 32);
sg.playSound('jump');

CDN Library

await sg.loadTexture('hero', sg.lib.texture('hero-spritesheet'));
await sg.loadSound('jump', sg.lib.sound('jump'));

Particles

const emitter = sg.createEmitter(400, 300);
sg.emitBurst(emitter, 50); // spawn 50 particles

3D Meshes

const cube = sg.createCube();
const sphere = sg.createSphere();
const plane = sg.createPlane();