BEDROCK · CONTRACT

BITMAPWIN SDK

BitmapWin is not a game. It is the layer games, tools, cities and autonomous systems are built on. The SDK is the contract both humans and AI agents write against — deliberately readable by a machine, so an agent can build a working experience without guessing.

SDK v0.2LIVE DATA· PRIMITIVES BACKED BY REAL SYSTEMS

LAND

LIVE DATA

Read a BITMAP's identity, holder, club, parcels and neighbours. Ownership is first-is-first on chain; the SDK never invents it.

> land.get(height)
> land.owner(height)
> land.neighbours(height, radius)
> land.rights(height, address)

BUILD

LIVE DATA

Attach models, pages and deployed extenders to land you control or were granted.

> build.models(height)
> build.deploy(extender, version, height)
> build.undeploy(deploymentId)

PLAYER

LIVE DATA

Position, velocity, direction, movement and animation state, health and combat state for the local player and interpolated peers.

> player.self()
> player.peers()
> player.onMove(cb)
> player.onHit(cb)

WORLD

LIVE DATA

The shared 1,000 × 1,000 world: chunks, districts, cursors, chat channels and the chain tip.

> world.tip()
> world.chunk(x, z)
> world.chat.send(text)
> world.presence()

ECONOMY

LIVE DATA

Listings, offers, confirmed sales, leases and BIT balances. Settlement stays on Bitcoin.

> economy.listings(height)
> economy.trades(height)
> economy.leases(height)
> economy.bit.balance(address)

SOCIAL

LIVE DATA

Profiles, builder identity, follows, watchlists and parties.

> social.profile(address)
> social.follow(address)
> social.party()

AI

COMING SOON

The agent surface: describe an experience, receive a manifest, review it, then publish it as a normal extender version. Nothing is generated behind your back.

> ai.plan(prompt)
> ai.review(planId)
> ai.publish(planId)

RUNTIME API — CODE THAT ACTUALLY RUNS

LIVE DATA· EXECUTES IN A SANDBOX ON DEPLOYED LAND

A published version can carry JavaScript. It runs in a sealed sandbox — no page, no network, no wallet — and can only describe objects, movement and quests, which every visitor standing on that BITMAP then sees.

[ WRITE AND RUN CODE NOW ]

world

LIVE DATA

Describe what stands on the tile. Every call returns a handle you can move, recolour or remove later — the world renders the result for everyone standing nearby.

> world.prop({ shape, x, z, y, w, h, d, color, rotationY, label, glow, interactive })Create a solid. Returns a handle.
> world.model({ inscriptionId, x, z, y, w, rotationY })Place an on-chain GLB/GLTF inscription.
> handle.set({ x, z, y, rotationY, color, label })Move or restyle a prop.
> handle.remove()Delete the prop.
> world.count()How many props are alive.

quest

LIVE DATA

Give visitors something to do. Quests appear in the world HUD for anyone on the tile and can change state as players act.

> quest.add({ id, title, detail, reward })Publish a quest.
> quest.state(id, 'open' | 'active' | 'done')Advance it.
> quest.remove(id)Withdraw it.

on

LIVE DATA

React to the simulation. Handlers are called by the runtime, never by the page, and a throwing handler stops the extender instead of breaking the world.

> on('tick', ({ time, dt, player }) => {})~15Hz. player is tile-local strides, or null when nobody is on the tile.
> on('interact', ({ propId, player }) => {})A visitor clicked an interactive prop.
> on('enter', ({ player }) => {})A visitor stepped onto the tile.
> on('leave', () => {})The tile is empty again.

state

LIVE DATA

Real world state, saved to the land. Anything you put in state comes back next session for every visitor, so buildings, NPCs and progress persist instead of resetting. Quest states and props created with `persist: true` are saved for you automatically. Signed-out visitors still play — their session simply is not written back.

> state.get(key, fallback)Read the shared record for this deployment.
> state.set(key, value)Save JSON — objects, arrays, numbers, strings.
> state.add(key, amount)Increment a saved counter and return it.
> state.remove(key)Forget one key.
> state.all()The whole shared record.
> state.player.get / set / add / remove / allPrivate per-visitor record (progress, inventory).
> world.prop({ id, persist: true, ... })Save this object's position, rotation, colour and label.

land

LIVE DATA

Read-only facts about the tile the code is deployed on. Ownership comes from the chain — the SDK never invents it.

> land.heightBITMAP number.
> land.clubClub this BITMAP belongs to.
> land.ownerCurrent holder address, or null.
> land.configThe JSON config chosen at deploy time.

util

LIVE DATA

Deterministic helpers. Randomness is seeded from the BITMAP number, so the same land always builds the same way for every visitor.

> random()Seeded 0..1.
> randomInt(min, max)Seeded integer.
> log(...values)Writes to the extender console (last 40 lines).

economy / social

COMING SOON

Reading listings, trades, leases, BIT balances and profiles from inside extender code is next. Until it ships, those surfaces stay in the app UI so nothing here pretends to be wired.

> economy.listings()Not available in v0.2.
> social.profile(address)Not available in v0.2.

TYPES INJECTED INTO EVERY SANDBOX

// BitmapWin SDK v0.2 — injected into every extender sandbox
declare const land: { height: number; club: string; owner: string | null; config: Record<string, unknown> };
declare function on(event: "tick" | "interact" | "enter" | "leave", handler: (event: any) => void): void;
declare function log(...values: unknown[]): void;
declare function random(): number;
declare function randomInt(min: number, max: number): number;

type Handle = {
  set(patch: Partial<{ x: number; y: number; z: number; rotationY: number; color: string; label: string | null }>): void;
  remove(): void;
  readonly id: string;
};

declare const world: {
  prop(spec: {
    shape?: "box" | "cylinder" | "sphere" | "cone" | "plane";
    id?: string;
    x?: number; y?: number; z?: number;
    w?: number; h?: number; d?: number;
    color?: string; rotationY?: number;
    label?: string; glow?: boolean; interactive?: boolean;
    /** save this object's place, rotation, colour and label to the land */
    persist?: boolean;
  }): Handle;
  model(spec: { inscriptionId: string; x?: number; y?: number; z?: number; w?: number; rotationY?: number; label?: string; persist?: boolean }): Handle;
  count(): number;
};

declare const quest: {
  add(spec: { id: string; title: string; detail?: string; reward?: string }): void;
  state(id: string, state: "open" | "active" | "done"): void;
  remove(id: string): void;
};

type StateBucket = {
  get<T = unknown>(key: string, fallback?: T): T;
  set(key: string, value: unknown): void;
  add(key: string, amount: number): number;
  remove(key: string): void;
  all(): Record<string, unknown>;
};

/** Saved world state. Shared record for everyone, plus a private per-visitor record. */
declare const state: StateBucket & { player: StateBucket };

PIRATE HARBOR

Pier, harbour master, three sailing ships and two quests.

SIGNAL TAVERN

A meeting hall with a beacon and a greeting quest.

INSCRIPTION GALLERY

Pedestals that render on-chain models listed in deploy config.

WELCOME GATE

Arrival gate, control hints and a saved guest counter. Good first build for any land.

SKY PARKOUR

Six floating checkpoints and a summit flag, with progress saved per visitor.

BURIED CACHE

Five hidden caches per land, remembered for each visitor who digs them.

CAMPFIRE MEETUP

Seating circle, live fire and a shared tally of nights spent together.

LAND NOTICE BOARD

Market stall showing a headline, note and contact set in deploy config.

MAX 240 OBJECTS
MAX 24 QUESTS
MAX 24000 CODE BYTES

LAND PERMISSIONS

Every extender declares what it needs on a tile. An owner grants rights explicitly; a deployment is refused when the live chain says the caller has none.

VIEW
ENTER
BUILD
EDIT
DEPLOY
MANAGE
LEASE
MONETIZE

[ START BUILDING ][ SEE WHAT EXISTS ]