skinview3d-node 3.4.2-node.1

package/libs/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './process.js';
+export * from './load-image.js';

package/libs/utils/load-image.d.ts

@@ -0,0 +1,7 @@
+import { Canvas, Image } from 'skia-canvas';
+import { DataTexture } from 'three';
+export type RemoteImage = string | Buffer | {
+    src: string;
+};
+export declare function loadImage(source: RemoteImage): Promise<Image>;
+export declare function canvas2DataTexture(canvas: Canvas): DataTexture;

package/libs/utils/process.d.ts

@@ -0,0 +1,7 @@
+import { TextureCanvas, TextureSource, ModelType } from './types.js';
+export declare function loadSkinToCanvas(canvas: TextureCanvas, image: TextureSource): void;
+export declare function loadCapeToCanvas(canvas: TextureCanvas, image: TextureSource): void;
+export declare function inferModelType(canvas: TextureCanvas): ModelType;
+export declare function loadEarsToCanvas(canvas: TextureCanvas, image: TextureSource): void;
+export declare function loadEarsToCanvasFromSkin(canvas: TextureCanvas, image: TextureSource): void;
+export declare function loadArmorToCanvas(canvas: TextureCanvas, layer1Image: TextureSource | null | undefined, layer2Image: TextureSource | null | undefined): void;

package/libs/utils/types.d.ts

@@ -0,0 +1,5 @@
+import { Canvas, Image } from 'skia-canvas';
+export type TextureCanvas = Canvas;
+export type TextureSource = TextureCanvas | Image;
+export type ModelType = 'default' | 'slim';
+export declare function isTextureSource(value: unknown): value is TextureSource;

package/libs/viewer.d.ts

@@ -0,0 +1,328 @@
+import { type ModelType, type RemoteImage, type TextureSource } from './utils/index.js';
+import { Color, type ColorRepresentation, PointLight, Group, PerspectiveCamera, Scene, Texture, WebGLRenderer, AmbientLight, type Mapping } from 'three';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js';
+import { ShaderPass } from 'three/examples/jsm/postprocessing/ShaderPass.js';
+import { PlayerAnimation } from './animation.js';
+import { type BackEquipment, PlayerObject } from './model.js';
+import { NameTagObject } from './nametag.js';
+import { Canvas, ExportFormat, ExportOptions } from 'skia-canvas';
+import gl from 'gl';
+export interface LoadOptions {
+    /**
+     * Whether to make the object visible after the texture is loaded.
+     *
+     * @defaultValue `true`
+     */
+    makeVisible?: boolean;
+}
+export interface SkinLoadOptions extends LoadOptions {
+    /**
+     * The model of the player (`"default"` for normal arms, and `"slim"` for slim arms).
+     *
+     * When set to `"auto-detect"`, the model will be inferred from the skin texture.
+     *
+     * @defaultValue `"auto-detect"`
+     */
+    model?: ModelType | 'auto-detect';
+    /**
+     * Whether to display the ears drawn on the skin texture.
+     *
+     * - `true` - Display the ears drawn on the skin texture.
+     * - `"load-only"` - Loads the ear texture, but do not make them visible.
+     *   You can make them visible later by setting `PlayerObject.ears.visible` to `true`.
+     * - `false` - Do not load or show the ears.
+     *
+     * @defaultValue `false`
+     */
+    ears?: boolean | 'load-only';
+}
+export interface CapeLoadOptions extends LoadOptions {
+    /**
+     * The equipment (`"cape"` or `"elytra"`) to show when the cape texture is loaded.
+     *
+     * If `makeVisible` is set to false, this option will have no effect.
+     *
+     * @defaultValue `"cape"`
+     */
+    backEquipment?: BackEquipment;
+}
+export interface EarsLoadOptions extends LoadOptions {
+    /**
+     * The type of the provided ear texture.
+     *
+     * - `"standalone"` means the provided texture is a 14x7 image that only contains the ears.
+     * - `"skin"` means the provided texture is a skin texture with ears, and we will use its ear part.
+     *
+     * @defaultValue `"standalone"`
+     */
+    textureType?: 'standalone' | 'skin';
+}
+export interface SkinViewerOptions {
+    /**
+     * The canvas where the renderer draws its output.
+     *
+     * @defaultValue If unspecified, a new canvas element will be created.
+     */
+    canvas?: Canvas;
+    ctx?: ReturnType<typeof gl>;
+    /**
+     * The CSS width of the canvas.
+     */
+    width?: number;
+    /**
+     * The CSS height of the canvas.
+     */
+    height?: number;
+    /**
+     * The pixel ratio of the canvas.
+     *
+     * When set to `"match-device"`, the current device pixel ratio will be used,
+     * and it will be automatically updated when the device pixel ratio changes.
+     *
+     * @defaultValue `"match-device"`
+     */
+    pixelRatio?: number;
+    /**
+     * The skin texture of the player.
+     *
+     * @defaultValue If unspecified, the skin will be invisible.
+     */
+    skin?: RemoteImage | TextureSource;
+    /**
+     * The model of the player (`"default"` for normal arms, and `"slim"` for slim arms).
+     *
+     * When set to `"auto-detect"`, the model will be inferred from the skin texture.
+     *
+     * If the `skin` option is not specified, this option will have no effect.
+     *
+     * @defaultValue `"auto-detect"`
+     */
+    model?: ModelType | 'auto-detect';
+    /**
+     * The cape texture of the player.
+     *
+     * @defaultValue If unspecified, the cape will be invisible.
+     */
+    cape?: RemoteImage | TextureSource;
+    capeLoadOptions?: CapeLoadOptions;
+    /**
+     * The ear texture of the player.
+     *
+     * When set to `"current-skin"`, the ears drawn on the current skin texture (as is specified in the `skin` option) will be shown.
+     *
+     * To use an individual ear texture, you have to specify the `textureType` and the `source` option.
+     * `source` is the texture to use, and `textureType` can be either `"standalone"` or `"skin"`:
+     *   - `"standalone"` means the provided texture is a 14x7 image that only contains the ears.
+     *   - `"skin"` means the provided texture is a skin texture with ears, and we will show its ear part.
+     *
+     * @defaultValue If unspecified, the ears will be invisible.
+     */
+    ears?: 'current-skin' | {
+        textureType: 'standalone' | 'skin';
+        source: RemoteImage | TextureSource;
+    };
+    /**
+     * Whether to preserve the buffers until manually cleared or overwritten.
+     *
+     * @defaultValue `false`
+     */
+    preserveDrawingBuffer?: boolean;
+    /**
+     * Whether to pause the rendering and animation loop.
+     *
+     * @defaultValue `false`
+     */
+    /**
+     * The background of the scene.
+     *
+     * @defaultValue transparent
+     */
+    background?: ColorRepresentation | Texture;
+    /**
+     * The panorama background to use.
+     *
+     * This option overrides the `background` option.
+     */
+    panorama?: RemoteImage | TextureSource;
+    /**
+     * Camera vertical field of view, in degrees.
+     *
+     * The distance between the player and the camera will be automatically computed from `fov` and `zoom`.
+     *
+     * @defaultValue `50`
+     *
+     * @see {@link SkinViewer.adjustCameraDistance}
+     */
+    fov?: number;
+    /**
+     * Zoom ratio of the player.
+     *
+     * This value affects the distance between the object and the camera.
+     * When set to `1.0`, the top edge of the player's head coincides with the edge of the canvas.
+     *
+     * The distance between the player and the camera will be automatically computed from `fov` and `zoom`.
+     *
+     * @defaultValue `0.9`
+     *
+     * @see {@link SkinViewer.adjustCameraDistance}
+     */
+    zoom?: number;
+    /**
+     * Whether to enable mouse control function.
+     *
+     * This function is implemented using {@link OrbitControls}.
+     * By default, zooming and rotating are enabled, and panning is disabled.
+     *
+     * @defaultValue `true`
+     */
+    enableControls?: boolean;
+    /**
+     * The animation to play on the player.
+     *
+     * @defaultValue If unspecified, no animation will be played.
+     */
+    animation?: PlayerAnimation;
+    /**
+     * The name tag to display above the player.
+     *
+     * @defaultValue If unspecified, no name tag will be displayed.
+     * @see {@link SkinViewer.nameTag}
+     */
+    nameTag?: NameTagObject | string;
+}
+/**
+ * The SkinViewer renders the player on a canvas.
+ */
+export declare class SkinViewer {
+    /**
+     * The canvas where the renderer draws its output.
+     */
+    readonly canvas: Canvas;
+    readonly ctx: ReturnType<typeof gl>;
+    readonly scene: Scene;
+    readonly camera: PerspectiveCamera;
+    readonly renderer: WebGLRenderer;
+    /**
+     * The OrbitControls component which is used to implement the mouse control function.
+     *
+     * @see {@link https://threejs.org/docs/#examples/en/controls/OrbitControls | OrbitControls - three.js docs}
+     */
+    /**
+     * The player object.
+     */
+    readonly playerObject: PlayerObject;
+    /**
+     * A group that wraps the player object.
+     * It is used to center the player in the world.
+     */
+    readonly playerWrapper: Group;
+    readonly globalLight: AmbientLight;
+    readonly cameraLight: PointLight;
+    readonly composer: EffectComposer;
+    readonly renderPass: RenderPass;
+    readonly fxaaPass: ShaderPass;
+    readonly skinCanvas: Canvas;
+    readonly capeCanvas: Canvas;
+    readonly earsCanvas: Canvas;
+    private skinTexture;
+    private capeTexture;
+    private earsTexture;
+    private backgroundTexture;
+    private _disposed;
+    private _zoom;
+    /**
+     * Whether to rotate the player along the y axis.
+     *
+     * @defaultValue `false`
+     */
+    autoRotate: boolean;
+    /**
+     * The angular velocity of the player, in rad/s.
+     *
+     * @defaultValue `1.0`
+     * @see {@link autoRotate}
+     */
+    autoRotateSpeed: number;
+    private _animation;
+    private _pixelRatio;
+    private _nameTag;
+    private nameTagYOffset;
+    private _loadPromiseArr;
+    /** 读取各部位 */
+    readonly ready: Promise<any>;
+    constructor(options?: SkinViewerOptions);
+    private updateComposerSize;
+    private recreateSkinTexture;
+    private recreateCapeTexture;
+    private recreateEarsTexture;
+    loadSkin(empty: null): void;
+    loadSkin<S extends TextureSource | RemoteImage>(source: S, options?: SkinLoadOptions): S extends TextureSource ? void : Promise<void>;
+    resetSkin(): void;
+    loadCape(empty: null): void;
+    loadCape<S extends TextureSource | RemoteImage>(source: S, options?: CapeLoadOptions): S extends TextureSource ? void : Promise<void>;
+    resetCape(): void;
+    loadEars(empty: null): void;
+    loadEars<S extends TextureSource | RemoteImage>(source: S, options?: EarsLoadOptions): S extends TextureSource ? void : Promise<void>;
+    resetEars(): void;
+    loadPanorama<S extends TextureSource | RemoteImage>(source: S): S extends TextureSource ? void : Promise<void>;
+    loadBackground<S extends TextureSource | RemoteImage>(source: S, mapping?: Mapping): S extends TextureSource ? void : Promise<void>;
+    toRGBA(): Uint8Array;
+    toBuffer(format?: ExportFormat, options?: ExportOptions): Buffer<ArrayBufferLike>;
+    /**
+     * Renders the scene to the canvas.
+     * This method does not change the animation progress.
+     */
+    render(): void;
+    renderAnimationFrame(progress: number, binary?: false): (() => Uint8Array);
+    renderAnimationFrame(progress: number, binary: true): (() => Buffer);
+    renderAnimationLoop(frames?: number, binary?: false): (() => Uint8Array)[];
+    renderAnimationLoop(frames: number, binary: true): (() => Buffer)[];
+    setSize(width: number, height: number): void;
+    dispose(): void;
+    get disposed(): boolean;
+    /**
+     * Whether rendering and animations are paused.
+     * Setting this property to true will stop both rendering and animation loops.
+     * Setting it back to false will resume them.
+     */
+    get width(): number;
+    set width(newWidth: number);
+    get height(): number;
+    set height(newHeight: number);
+    get background(): null | Color | Texture;
+    set background(value: null | ColorRepresentation | Texture);
+    adjustCameraDistance(): void;
+    resetCameraPose(): void;
+    get fov(): number;
+    set fov(value: number);
+    get zoom(): number;
+    set zoom(value: number);
+    get pixelRatio(): number;
+    set pixelRatio(newValue: number);
+    /**
+     * The animation that is current playing, or `null` if no animation is playing.
+     *
+     * Setting this property to a different value will change the current animation.
+     * The player's pose and the progress of the new animation will be reset before playing.
+     *
+     * Setting this property to `null` will stop the current animation and reset the player's pose.
+     */
+    get animation(): PlayerAnimation | null;
+    set animation(animation: PlayerAnimation | null);
+    /**
+     * The name tag to display above the player, or `null` if there is none.
+     *
+     * When setting this property to a `string` value, a {@link NameTagObject}
+     * will be automatically created with default options.
+     *
+     * @example
+     * ```
+     * skinViewer.nameTag = "hello";
+     * skinViewer.nameTag = new NameTagObject("hello", { textStyle: "yellow" });
+     * skinViewer.nameTag = null;
+     * ```
+     */
+    get nameTag(): NameTagObject | null;
+    set nameTag(newVal: NameTagObject | string | null);
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+	"name": "skinview3d-node",
+	"version": "3.4.2-node.1",
+	"description": "Three.js powered Minecraft skin viewer for Node.js",
+	"main": "libs/skinview3d.cjs",
+	"type": "module",
+	"exports": {
+		"import": "./libs/skinview3d.mjs",
+		"require": "./libs/skinview3d.cjs",
+		"types": "./libs/skinview3d.d.ts"
+	},
+	"scripts": {
+		"clean": "rimraf libs bundles",
+		"build:bundles": "rollup -c --configPlugin=swc3",
+		"build:docs": "typedoc src/viewer.ts",
+		"build:preview": "vite build",
+		"build": "npm-run-all --parallel build:bundles build:preview",
+		"format": "prettier src examples eslint.config.js --write",
+		"test:lint": "eslint src examples eslint.config.js",
+		"test": "npm run test:lint",
+		"dev:watch:modules": "tsc -w --preserveWatchOutput --declaration --sourceMap --outDir libs -p .",
+		"dev:watch:bundles": "rollup -w --no-watch.clearScreen -c --configPlugin=swc3",
+		"dev": "vite",
+		"preview": "vite preview",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ltxhhz/skinview3d-node.git"
+	},
+	"author": "ltxhhz <ltxhhz@gmail.com> (https://github.com/ltxhhz)",
+	"contributors": [
+		"Sean Boult <sean@boult.me> (https://github.com/Hacksore)",
+		"Pig Fang <g-plane@hotmail.com> (https://github.com/g-plane)",
+		"printempw <h@prinzeugen.net> (https://github.com/printempw)",
+		"Kent Rasmussen <hyprkookeez@gmail.com> (https://github.com/earthiverse)"
+	],
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/ltxhhz/skinview3d-node/issues"
+	},
+	"homepage": "https://github.com/ltxhhz/skinview3d-node",
+	"files": [
+		"libs",
+		"bundles",
+		"assets"
+	],
+	"dependencies": {
+		"@types/three": "^0.156.0",
+		"pngjs": "^7.0.0",
+		"skia-canvas": "^3.0.8",
+		"skinview-utils": "^0.7.1",
+		"three": "^0.156.0"
+	},
+	"devDependencies": {
+		"@rollup/plugin-commonjs": "^21.1.0",
+		"@rollup/plugin-node-resolve": "^15.0.2",
+		"@rollup/plugin-typescript": "^8.5.0",
+		"@swc/core": "^1.3.53",
+		"@typescript-eslint/eslint-plugin": "^8.31.1",
+		"@typescript-eslint/parser": "^8.31.1",
+		"@yushijinhun/three-minifier-rollup": "^0.4.0",
+		"eslint": "^9.26.0",
+		"eslint-plugin-tsdoc": "^0.2.17",
+		"gl": "^8.1.6",
+		"jszip": "^3.10.1",
+		"local-web-server": "^5.2.1",
+		"npm-run-all": "^4.1.5",
+		"prettier": "^3.0.3",
+		"rimraf": "^3.0.2",
+		"rollup": "^3.20.7",
+		"rollup-plugin-swc3": "^0.8.1",
+		"tslib": "^2.8.1",
+		"typedoc": "^0.25.7",
+		"typescript": "^5.0.4",
+		"vite": "^5.4.7"
+	}
+}