Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
/**
* @title WorldMoves
* @notice Event-only on-chain move-commit stream for three.ws's real-time
* worlds. Designed to be called every ~0.45s per player — BSC's live
* block time (Fermi hardfork, BEP-619/590, 2026-01-14) — so the design
* goal is minimal gas per call, not queryable on-chain state.
*
* `move()` writes zero storage slots: it only emits `Moved`. Indexers
* reconstruct live positions by subscribing to the event stream (the
* same pattern a UDP-style game snapshot would use, but with EVM
* finality). Storage is opt-in via `checkpoint()`, used only when a
* caller actually needs a queryable "last known position" (e.g. a
* freshly-joining client backfilling world state before the event
* stream catches it up).
*
* No admin key, no owner, no upgradeability, no pausability — the
* entire contract is three externally-callable state transitions
* (`join`, `move`, `leave`) plus one storage-writing variant
* (`checkpoint`). Nothing here can be rugged or bricked.
*
* @dev Coordinate bounds: world-space is a signed 24-bit range,
* [-8_388_608, 8_388_607], stored in `int32` params for calldata/ABI
* simplicity but validated against the tighter 24-bit bound. That's an
* 8.39km cube at 1 unit = 1mm, or an 8390km cube at 1 unit = 1m — enough
* headroom for any three.ws scene while cheaply rejecting garbage/attack
* input (e.g. int32 overflow griefing an indexer). Out-of-range
* coordinates REVERT (chosen over clamping: clamping would silently
* teleport a player to the wall and desync client-predicted state from
* the on-chain log; reverting makes bad input the caller's problem, and
* failed moves cost the spammer gas without corrupting the stream for
* everyone else).
*/
contract WorldMoves {
/// @notice Inclusive bound for x/y/z on every move/checkpoint. +/- 2^23.
int32 public constant COORD_MIN = -8_388_608;
int32 public constant COORD_MAX = 8_388_607;
/// @dev worldId => player => last checkpointed state. Only populated for
/// callers that opt into `checkpoint()`; `move()` never touches this.
mapping(uint32 => mapping(address => Position)) private _checkpoints;
struct Position {
int32 x;
int32 y;
int32 z;
uint16 facing;
uint64 blockNumber;
uint64 timestamp;
bool exists;
}
/// @notice Emitted on every move. The primary real-time data feed —
/// indexers/clients subscribe to this instead of polling storage.
event Moved(
uint32 indexed worldId,
address indexed player,
int32 x,
int32 y,
int32 z,
uint16 facing,
uint256 blockNumber,
uint256 timestamp
);
/// @notice Emitted when a player announces presence in a world.
event Joined(uint32 indexed worldId, address indexed player, uint256 timestamp);
/// @notice Emitted when a player announces departure from a world.
event Left(uint32 indexed worldId, address indexed player, uint256 timestamp);
/// @notice Emitted by `checkpoint()` — the only call that writes storage.
event CheckpointSet(
uint32 indexed worldId,
address indexed player,
int32 x,
int32 y,
int32 z,
uint16 facing,
uint256 blockNumber,
uint256 timestamp
);
error CoordinateOutOfBounds();
/// @notice Announce presence in `worldId`. Purely an event — no storage,
/// no membership check, no capacity limit. Callable freely and
/// repeatedly; consumers treat the latest `Joined`/`Left` per
/// (worldId, player) as the presence state.
function join(uint32 worldId) external {
emit Joined(worldId, msg.sender, block.timestamp);
}
/// @notice Announce departure from `worldId`. See `join` for semantics.
function leave(uint32 worldId) external {
emit Left(worldId, msg.sender, block.timestamp);
}
/// @notice Commit a move. Event-only — no SSTORE — so gas stays flat no
/// matter how many times a player calls this (the whole point:
/// callers are expected to spam this every ~0.45s).
/// @param worldId Logical world/room identifier.
/// @param x,y,z Position, bounded to [COORD_MIN, COORD_MAX].
/// @param facing Heading/orientation, caller-defined units (e.g.
/// millidegrees 0..35999, or a packed quaternion index).
/// Not range-checked: any uint16 is a valid facing.
function move(uint32 worldId, int32 x, int32 y, int32 z, uint16 facing) external {
_checkBounds(x, y, z);
emit Moved(worldId, msg.sender, x, y, z, facing, block.number, block.timestamp);
}
/// @notice Persist the caller's latest position/facing in `worldId` as
/// queryable storage. Opt-in and separate from `move()` on
/// purpose: most callers never need this (they read the `Moved`
/// event log), so paying an SSTORE on every tick would be wasted
/// gas for the common case. Use this for the rare read path — a
/// client that just connected and needs a synchronous "where is
/// everyone right now" without replaying the whole event log.
function checkpoint(uint32 worldId, int32 x, int32 y, int32 z, uint16 facing) external {
_checkBounds(x, y, z);
_checkpoints[worldId][msg.sender] =
Position({x: x, y: y, z: z, facing: facing, blockNumber: uint64(block.number), timestamp: uint64(block.timestamp), exists: true});
emit CheckpointSet(worldId, msg.sender, x, y, z, facing, block.number, block.timestamp);
}
/// @notice Read a player's last checkpointed position in `worldId`.
/// Returns `exists = false` (and zeroed fields) if the player has
/// never called `checkpoint()` in that world — `move()` alone
/// never populates this.
function getCheckpoint(uint32 worldId, address player)
external
view
returns (int32 x, int32 y, int32 z, uint16 facing, uint64 blockNumber, uint64 timestamp, bool exists)
{
Position storage p = _checkpoints[worldId][player];
return (p.x, p.y, p.z, p.facing, p.blockNumber, p.timestamp, p.exists);
}
function _checkBounds(int32 x, int32 y, int32 z) private pure {
if (x < COORD_MIN || x > COORD_MAX) revert CoordinateOutOfBounds();
if (y < COORD_MIN || y > COORD_MAX) revert CoordinateOutOfBounds();
if (z < COORD_MIN || z > COORD_MAX) revert CoordinateOutOfBounds();
}
}