@alexislours/ltd-sharemii 1.0.0

package/README.md

@@ -0,0 +1,35 @@
+# @alexislours/ltd-sharemii
+
+Codec for the game's Mii and UGC (user-generated content) share format. Extracts a Mii or a UGC item (clothing, food, goods, painting, ...) out of a parsed save into a portable share file, and applies a share file back into a save. Depends only on [`@alexislours/ltd-savedata`](../ltd-savedata).
+
+A share file is a small binary blob carved out of the save's typed fields. Textures and canvases that don't fit inline travel alongside it as named "sidecar" files. This package owns the binary codec and the apply/extract logic; how sidecars are packed for transport (a zip, a folder of files) is left to the caller.
+
+## Install
+
+```sh
+npm install @alexislours/ltd-sharemii
+```
+
+## Usage
+
+```ts
+import { decode, parseSav } from '@alexislours/ltd-savedata';
+import { MII_SCHEMA, PLAYER_SCHEMA } from '@alexislours/ltd-savedata/schema';
+import { extractMii, applyMii, EMPTY_SIDECAR } from '@alexislours/ltd-sharemii';
+
+const saves = {
+  mii: decode(MII_SCHEMA, parseSav(miiBytes)),
+  player: decode(PLAYER_SCHEMA, parseSav(playerBytes)),
+};
+
+const share = extractMii(saves, slot, EMPTY_SIDECAR);
+applyMii(destSaves, destSlot, share.bytes, share.sidecar);
+```
+
+## Sidecars
+
+The codec speaks `SidecarSource` (a `Map<string, Uint8Array>`) and `SidecarFile`, never files or archives. `isSidecarFileName` and `isJunkArchiveEntry` help a host filter incoming names. Packing those bytes into a zip or reading them from a dropped folder is a transport concern the host owns.
+
+## License
+
+AGPL-3.0-or-later

package/dist/applyMii.d.ts

@@ -0,0 +1,21 @@
+import { type MiiSaves } from './savAccess.js';
+import { type SidecarFile, type SidecarSource } from './sidecar.js';
+export declare const MII_SLOTS = 70;
+export declare const FP_STATE_UNUSED: number;
+export type MiiSlotInfo = {
+    slot: number;
+    empty: boolean;
+    name: string;
+};
+export declare function listMiiSlots(saves: MiiSaves): MiiSlotInfo[];
+export type ExtractMiiResult = {
+    bytes: Uint8Array;
+    fileName: string;
+    miiName: string;
+    facepaint: SidecarFile[];
+};
+export declare function extractMii(saves: MiiSaves, slot: number, sidecar?: SidecarSource): ExtractMiiResult;
+export type ApplyMiiResult = {
+    facepaintWrites: SidecarFile[];
+};
+export declare function applyMii(saves: MiiSaves, slot: number, ltdBytes: Uint8Array, sidecar?: SidecarSource): ApplyMiiResult;

package/dist/applyUgc.d.ts

@@ -0,0 +1,21 @@
+import { type PlayerOnlySaves } from './savAccess.js';
+import { type UgcKind } from './ugcKinds.js';
+import { type SidecarFile, type SidecarSource } from './sidecar.js';
+export type UgcSlotInfo = {
+    slot: number;
+    empty: boolean;
+    name: string;
+    isAddNew: boolean;
+};
+export declare function listUgcSlots(saves: PlayerOnlySaves, kind: UgcKind, sidecar?: SidecarSource): UgcSlotInfo[];
+export type ExtractUgcResult = {
+    bytes: Uint8Array;
+    fileName: string;
+    itemName: string;
+    textures: SidecarFile[];
+};
+export declare function extractUgc(saves: PlayerOnlySaves, slot: number, kind: UgcKind, sidecar?: SidecarSource): ExtractUgcResult;
+export type ApplyUgcResult = {
+    textureWrites: SidecarFile[];
+};
+export declare function applyUgc(saves: PlayerOnlySaves, slot: number, kind: UgcKind, ltdBytes: Uint8Array, isAdding: boolean, sidecar?: SidecarSource): ApplyUgcResult;

package/dist/codec.d.ts

@@ -0,0 +1,39 @@
+export type LtdMii = {
+    version: number;
+    /** Original version from the file before upgradeToV3; v1 has no personality data. */
+    originalVersion: number;
+    hasCanvas: boolean;
+    hasUgcTex: boolean;
+    miiBlock: Uint8Array;
+    personality: Uint8Array;
+    name: Uint8Array;
+    pronounce: Uint8Array;
+    sexuality: Uint8Array;
+    canvasTex: Uint8Array;
+    ugcTex: Uint8Array;
+};
+export declare function encodeLtdMii(m: LtdMii): Uint8Array;
+export declare function decodeLtdMii(bytes: Uint8Array): LtdMii;
+export type LtdUgc = {
+    kindIndex: number;
+    fields: Uint8Array;
+    vector: Uint8Array;
+    vector2: Uint8Array;
+    name: Uint8Array;
+    pronounce: Uint8Array;
+    goodsText?: Uint8Array;
+    goodsPronounce?: Uint8Array;
+    canvasTex: Uint8Array;
+    ugcTex: Uint8Array;
+    thumbTex: Uint8Array;
+};
+export declare function encodeLtdUgc(u: LtdUgc): Uint8Array;
+export type LtdUgcSection = {
+    kindIndex: number;
+    fieldsAndVectors: Uint8Array;
+    namesBlock: Uint8Array;
+    canvasTex: Uint8Array;
+    ugcTex: Uint8Array;
+    thumbTex: Uint8Array;
+};
+export declare function decodeLtdUgc(bytes: Uint8Array): LtdUgcSection;

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export type ShareMiiErrorCode = 'mii_not_initialized' | 'no_free_facepaint_slot' | 'ugc_missing_textures' | 'wrong_ugc_kind' | 'subtype_mismatch' | 'cannot_replace_kind' | 'invalid_ltd_file' | 'unsupported_ltd_version' | 'ltd_missing_marker' | 'invalid_ugc_kind_index' | 'invalid_zip' | 'save_format_error' | 'slot_out_of_range';
+export declare class ShareMiiError extends Error {
+    readonly code: ShareMiiErrorCode;
+    readonly params: Record<string, string | number>;
+    constructor(code: ShareMiiErrorCode, params?: Record<string, string | number>);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './sidecar.js';
+export * from './errors.js';
+export * from './utf16.js';
+export * from './ugcKinds.js';
+export * from './savAccess.js';
+export * from './codec.js';
+export * from './applyMii.js';
+export * from './applyUgc.js';