@ffxiark/character-viewer 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julian Dawson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @ffxiark/character-viewer
+
+WebGL2 3D character viewer for FFXI. Ships a React `<CharacterViewer>` component and a headless `CharacterSceneController` for custom integrations.
+
+## Install
+
+```bash
+pnpm add @ffxiark/character-viewer
+# or
+npm install @ffxiark/character-viewer
+```
+
+**Peer dependencies:** `react` and `react-dom` (^19).
+
+## Publishing
+
+Published to npm as [`@ffxiark/character-viewer`](https://www.npmjs.com/package/@ffxiark/character-viewer).
+
+**Prerequisites**
+
+1. npm org `@ffxiark` with publish access
+2. GitHub repo secret `NPM_TOKEN` (automation token with publish rights)
+
+**Release via GitHub**
+
+1. Bump `version` in `package.json` and commit
+2. Create a GitHub Release for that tag — the [Publish workflow](.github/workflows/publish.yml) runs tests, builds, and runs `pnpm publish`
+
+**Release locally**
+
+```bash
+pnpm test
+pnpm build
+npm login
+pnpm publish --access public
+```
+
+`prepublishOnly` runs tests and build automatically before publish.
+
+## Setup
+
+The viewer loads `.DAT` assets at runtime. Configure where they are fetched from once at app bootstrap:
+
+```typescript
+import { setAssetBaseUrl } from "@ffxiark/character-viewer";
+
+setAssetBaseUrl("/api/assets");
+```
+
+Consumers host `.DAT` files themselves (local FFXI install path, CDN, or app proxy). In `ffxiark-web`, assets are served from `/api/assets` via `FFXI_INSTALL_PATH`.
+
+Advanced: pass a custom loader with `configureAssetLoader(loader)` or reset with `resetAssetLoader()` in tests.
+
+## Quick start
+
+```tsx
+import { CharacterViewer } from "@ffxiark/character-viewer/react";
+
+const appearance = {
+  raceId: 0,
+  faceId: 0,
+  itemIds: { head: 16079, body: 12638 },
+};
+
+<CharacterViewer appearance={appearance} width="100%" minHeight={400} rotate />;
+```
+
+Omit `canvas.backgroundColor` for a transparent background (profile portraits). Use `canvas={{ backgroundColor: "#14171f" }}` for a solid panel.
+
+## Appearance input
+
+**Primary — `CharacterAppearanceById`** (Windower/API):
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `raceId` | `number` | 0–7 (HumeM, HumeF, ElvaanM, …) |
+| `faceId` | `number` | 0–31 |
+| `itemIds` | `Partial<Record<ModelSlotId, number>>` | Equipment item IDs per slot |
+
+**Runtime slots (flat):** `head`, `body`, `hands`, `legs`, `feet`, `main`, `sub`, `range`
+
+**Wardrobe picker taxonomy** (grouping only — still maps to flat slots at render time):
+
+| Group | Categories |
+|-------|------------|
+| Main | hand_to_hand, dagger, sword, great_sword, axe, great_axe, scythe, polearm, katana, great_katana, club, staff |
+| Sub | shield, hand_to_hand, dagger, sword, axe, katana, club |
+| Ranged | none, throwing, archery, marksmanship, stringed, wind, handbell |
+
+Helpers: `normalizeAppearance()`, `serializeAppearance()`, `validateAppearance()`, `hasItemModel()`, `isItemInCategory()`, `mapWindowerRaceId()`.
+
+Item→model mapping is internal to the package (`src/data/items.json`). Consumers pass item IDs only.
+
+## Props reference
+
+| Group | Prop | Default | Description |
+|-------|------|---------|-------------|
+| Data | `appearance` | — | Required character appearance |
+| 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` | — | `ViewerState` discriminated union |
+| Ref | `resetView`, `getOrbit`, `setOrbit`, `getState` | — | Imperative handle |
+
+See `docs/examples.md` for profile, wardrobe, and headless recipes.
+
+## Core exports (`@ffxiark/character-viewer`)
+
+- Types: `CharacterAppearance`, `ModelSlotId`, `ViewerState`, …
+- Slot taxonomy: `MAIN_WEAPON_TYPES`, `SUB_WEAPON_TYPES`, `RANGED_TYPES`, `ARMOR_SLOT_IDS`
+- Item metadata: `hasItemModel`, `isItemInCategory`, `getItemWeaponSkill`, `getItemPickerCategory`
+- `CharacterSceneController` — headless WebGL boot + render
+- `configureAssetLoader`, `setAssetBaseUrl`
+- `DEFAULT_VIEWER_BACKGROUND` — `"#14171f"`
+
+## React exports (`@ffxiark/character-viewer/react`)
+
+- `CharacterViewer`, `useCharacterScene`
+- `CharacterViewerProps`, `CharacterViewerHandle`, `RotateOptions`
+
+## Data and tables
+
+Item metadata lives in `src/data/items.json` and is updated manually. Each entry is sparse:
+
+```json
+{ "16583": { "m": 66, "sk": "great_sword", "slot": 1 } }
+```
+
+| Field | Meaning |
+|-------|---------|
+| `m` | Model index (omit when 0) |
+| `sk` | Weapon skill category (weapons only) |
+| `slot` | Equip slot bitmask (`1` = main, `32` = body, …) |
+
+`pnpm build:items` minifies `src/data/items.json` into `dist/items.json` (runs automatically after tsup in `pnpm build`).
+
+Mesh path tables (`equipment-lookup.json`, `file-table.json`, `race-config-indices.json`) live under `src/lib/ffxi/tables/generated/` and are bundled at build time.
+
+## Tests
+
+```bash
+pnpm test
+pnpm build
+```
+
+## Notes
+
+- Requires a local FFXI install or CDN hosting `.DAT` files; assets are not bundled.
+- Item IDs resolve to model indices via internal item metadata (not exposed as raw JSON).