@ffxiark/wardrobe

WebGL wardrobe for FFXI — React <Wardrobe> and headless CharacterSceneController. Code only: catalogs and ROM .DAT files are not in the npm package.

Install

pnpm add @ffxiark/wardrobe

Peer dependencies: react and react-dom (^19).

Data

| Catalog | Role | |---------|------| | item-models.json | Item → model / slot / skill + per-race rom_paths ("1"–"8") | | race-models.json | Race → base mesh paths + nested faces |

1. Sign in at ffxiark.com/wardrobe
2. Download the zip (item-models + race-models)
3. Host both JSONs and use mode: "files" with BYO ROM .DATs

mode: "jwt" / API catalogs need a session or API key — first-party ffxiark apps only.

Schemas: item-models · race-models

Usage

import { configureWardrobe } from "@ffxiark/wardrobe";

configureWardrobe({
  mode: "files",
  dataBaseUrl: "https://cdn.example.com/wardrobe-data",
  assetBaseUrl: "https://cdn.example.com/rom",
});

import { Wardrobe } from "@ffxiark/wardrobe/react";

<Wardrobe
  appearance={{ raceId: 1, faceId: 0, itemIds: { body: 10240 } }}
  preset="portrait"
  width="100%"
  minHeight={400}
/>

raceId is Windower PC 1–8. Presets: portrait | studio. More recipes (studio, data/assets embeds, useCharacterScene, headless) in EXAMPLES.md.

Props

| Group | Prop | Default | Description | |-------|------|---------|-------------| | Data | appearance | — | Required character appearance | | Data | preset | — | "portrait" | "studio" | | Data | data / assets | — | Catalog base + DAT root → mode: "files" | | Layout | width / height | "100%" | Shell dimensions | | Layout | minHeight | 320 | Minimum shell height | | Canvas | canvas.backgroundColor | transparent | Solid WebGL clear color | | Canvas | canvas.lighting | "default" | "default" | "day" | "night" | | Interaction | rotate | true | Drag orbit + optional auto-spin | | Interaction | zoom | false | Wheel zoom on camera radius | | Interaction | pause | offscreen auto-pause | true pauses render loop | | UI | fallbacks | built-in | Loading / empty / error slots | | UI | overlay | — | Custom overlay render prop | | Callback | onStateChange | — | WardrobeState discriminated union | | Ref | resetView, getOrbit, setOrbit, getState | — | Imperative handle |

Exports

• @ffxiark/wardrobe — configureWardrobe, ensureWardrobeData, appearance helpers, CharacterSceneController
• @ffxiark/wardrobe/react — Wardrobe, useCharacterScene

Publishing

Bump version, create a GitHub Release — the publish workflow runs pnpm test, pnpm build, and pnpm publish.