embed isometric
rooms with one
script tag.

dev playgrounds

Mobile-first, in-memory testers on this site — no Nakama, no account. Use them while building the client: preview every avatar effect, edit looks in a full wardrobe, and inspect furni from the CDN catalog.

avatars & effects

Render guest avatars outside a room or inside one: look strings, eight-way facing, action bits (Sit, Wave, Dance, …), smooth tile walks, and optional effect ids resolved through effectmap.xml with .ducket DKFE sprites from the CDN.

minimal bootstrap

One createWorld call boots Pixi, mounts a canvas, and readies the avatar manager. spawn() returns an AvatarHandle with first-class navigateTo (BFS pathfinding through the room grid), walkTo (scripted straight-line walks), setLook, face, and typed pointer events — no position-function wiring, no iso math.

var world = await DucketSuites.createWorld({
  mount: "#stage",
  tilemap: null, // standalone-avatar mode
});

var alice = await world.avatars.spawn({
  look: "hd-180-1.ch-255-66.lg-280-110.sh-305-62.hr-828-61",
  at:   { x: 2, y: 2 },
  facing: DucketSuites.Direction.South,
});

// optional named effect (resolved via effectmap + DKFE on CDN)
alice.setEffect("dance.1");
alice.do(DucketSuites.AvatarAction.Dance);

navigation (pathfinding)

navigateTo uses BFS over the room tile grid to find the shortest walkable path, then walks tile-by-tile at a consistent per-tile speed. Calling it again while the avatar is walking supersedes the old path — the avatar finishes its current tile and re-routes. Use walkTo when you supply the path yourself (scripted sequences, cutscenes).

// click-to-move: pathfinds through walls + stairs automatically
world.events.on("tile:click", (tile) => {
  void alice.navigateTo(tile);
});

// abandon the current path (finishes current tile, then stops)
alice.cancelNavigation();

// scripted sequence: supply your own path with walkTo
await alice.walkTo({ x: 3, y: 2 });
await alice.walkTo({ x: 3, y: 4 });
alice.face(DucketSuites.Direction.South);

api reference

createWorld(options)

The only entry point. Returns a World bound to a mount element, with lazy avatar + furniture managers and a typed event bus.

World

AvatarHandle

Returned by world.avatars.spawn({ look, at, facing, … }). Every mutator that triggers async work returns a Promise so you can chain.

FurnitureHandle

Returned by world.furniture.place({ type, at, facing, … }) (pass an array for batch).

Direction

Enum replacing raw 0/2/4/6. Direction.North, NorthEast, East, … plus helpers from(n), opposite(d), name(d).

tilemaps

Tilemaps are multiline strings. Each character is a tile:

• x — void (no tile)
• 0–9 — floor at that height level
• A row with no leading x is the door row
• Height transitions auto-generate stairs

// simple flat room with door
var flat = [
  "xxxxx",
  "x0000",
  "00000",   // ← door row
  "x0000",
  "x0000",
].join("\n");

// raised platform — stairs auto-generated
var raised = [
  "xxxxxxxxx",
  "x00000000",
  "000000000",
  "x00111100",   // height 1 platform
  "x00111100",
  "x00000000",
].join("\n");

furniture

batch placement (recommended)

Pass an array of descriptors — bundles are deduped, fetched in parallel, and auto-stacked when at.z is omitted.

var Dir = DucketSuites.Direction;

await world.furniture.place([
  { type: "throne",              at: { x: 3, y: 3 }, facing: Dir.South },
  { type: "nft_h23_trippy_aloe", at: { x: 1, y: 1 }, facing: Dir.East, state: "0" },
  { type: "hc23_11",            at: { x: 5, y: 2 }, facing: Dir.West, state: "0" },
]);

individual by direct URL

var chair = await world.furniture.place({
  url: "https://cdn.ducket.net/hof_furni/65456/throne.ducket",
  at: { x: 4, y: 3 },
  facing: DucketSuites.Direction.East,
});

// move / rotate / animate via the handle
chair.moveTo({ x: 6, y: 3 });
chair.face(DucketSuites.Direction.South);

FurnitureDescriptor

behaviours & logic

Habbo's authoring pipeline tags every furni with a logic type — a short string like furniture_dice, furniture_multistate, or furniture_random_state. The ducket runtime mirrors that: each logic type maps to a behaviour (a state machine that drives the piece), and the right behaviour auto-attaches when a bundle loads.

Most of the time you don't touch any of this. A dice rolls on double-click. A multistate door cycles. A random-state tree picks its look on spawn. This port follows reference IFurnitureBehavior: behaviours attach via setParent and wire pointer handlers themselves. For programmatic control, use FurnitureHandle.getBehavior(Ctor) and call behaviour methods (roll(), next(), …).

built-in logic types

generic use

Branch on getBehavior for the logic you care about, or subscribe to world.events and dispatch yourself.

var { FurnitureDiceBehavior, FurnitureMultiStateBehavior } = DucketSuites;

var piece = await world.furniture.place({
  type: "edicehc",     // or a multistate / one-way classname
  at:   { x: 2, y: 2 },
});

var dice = piece.getBehavior(FurnitureDiceBehavior);
if (dice) {
  await dice.roll();   // programmatic roll (double-click also wired in-engine)
} else {
  piece.getBehavior(FurnitureMultiStateBehavior)?.next();
}

console.log(piece.logic);         // "furniture_dice"
console.log(piece.visualization); // "furniture_animated"

specialised use

When you need behaviour-specific methods (roll(value) on a dice, setIndex(i) on a multistate), look them up by constructor.

var { FurnitureDiceBehavior } = DucketSuites;

var dice = await world.furniture.place({
  type: "edicehc", at: { x: 2, y: 2 },
});

var behaviour = dice.getBehavior(FurnitureDiceBehavior);
await behaviour?.roll(6);   // force land on six
behaviour?.close();          // no face shown

registering your own

Host apps can plug in custom behaviours at app init. Key on the manifest's Habbo logic tag — the same string index.bin ships upstream.

import { registerLogicBehavior } from "@suites-public/index";

// Every furni whose manifest.lo === "furniture_jukebox" gets one:
registerLogicBehavior(["furniture_jukebox"], () => new JukeboxBehavior());

Writing your own behaviour? Implement setParent(furni) for attachment (reference parity). Register pointer UX with furni.addPointerInteractionListener(kind, fn) and keep the returned unsubscribe; call it from destroy() alongside any timers. Do not assign onClick / onDoubleClick on furniture — that bypasses the merged pipeline.

Porting a pre-v1.4 bundle? Re-run the migration pipeline (tsx ducket/bin/migrate-shroom.ts) and the fresh encode will populate manifest.lo / manifest.vz from the source index.bin. The ducket corpus is the runtime's single source of truth for interactivity — no classname lookup tables, no external metadata, no .shroom dependency after migration.

events

One typed bus for everything — subscribe with world.events.on(...), returns an unsubscribe function.

world.events.on("tile:click", (tile) => {
  console.log("clicked", tile.x, tile.y, tile.z);
});

world.events.on("avatar:click", ({ avatar }) => {
  avatar.toggle(DucketSuites.AvatarAction.Wave);
});

world.events.on("furni:hover", ({ furniture }) => {
  console.log("over", furniture.type, furniture.tile);
});