@r2o3/rgskin-nodejs 0.0.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2025 menvae
+
+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,350 @@
+# rgskin
+A library for loading and creating skins for various rhythm games. It supports cross-platform usage including Web and Node.js environments via WebAssembly (WASM).
+
+## Table of Contents
+
+- [Rust Usage](#rust-usage)
+    - [Installation](#installation)
+    - [API Reference](#api-reference)
+        - [Importing/Loading Skins](#importingloading-skins)
+        - [Creating Skins](#creating-skins)
+        - [Exporting Skins](#exporting-skins)
+- [JavaScript/TypeScript Usage](#javascripttypescript-usage)
+    - [Installation](#installation-1)
+    - [API Reference](#api-reference-1)
+        - [Initialization](#initialization)
+        - [Importing/Loading Skins](#importingloading-skins-1)
+        - [Creating Skins](#creating-skins-1)
+        - [Exporting Skins](#exporting-skins-1)
+- [Building](#building)
+    - [Rust Library](#rust-library)
+    - [WASM Bindings](#wasm-bindings)
+- [License](#license)
+
+## Rust Usage
+
+### Installation
+Add this to your `Cargo.toml`:
+```toml
+[dependencies]
+rgskin = "0.0.1"
+```
+
+Or run:
+```sh
+cargo add rgskin
+```
+
+### API Reference
+
+#### Importing/Loading Skins
+
+##### Recommended way of Loading a skin
+
+```rust
+use rgskin::prelude::*;
+
+// importing a skin from a directory
+let osu_skin = import::osu::skin_from_dir("path/to/skin").expect("Failed to import skin!");
+let fluxis_skin = import::fluxis::skin_from_dir("path/to/skin").expect("Failed to import skin!");
+```
+
+##### Manually loading a skin
+
+```rust
+use rgskin::prelude::*;
+
+// create a new texture store, this is where the actual textures will be stored
+let mut textures = TextureStore::new();
+
+// you can import textures from a directory like this:
+textures = import::all_textures_from_dir("path/to/skin")?;
+
+// or alternatively if you parse the skin config first, you can import only the textures you need like this:
+let raw_str = import::osu::ini_str_from_dir("path/to/skin");
+let skin_config = OsuSkinIni::from_str(&raw_str)?;
+
+// since get_required_texture_paths returns a HashSet, we need to convert it to a Vec<&str> for the import function
+let required_texture_paths_set = skin_config.get_required_texture_paths();
+let required_texture_paths = required_texture_paths_set.iter().map(|s| s.as_str()).collect::<Vec<_>>();
+
+textures = import::textures_from_dir("path/to/skin", &required_texture_paths)?;
+
+// now you can create a skin from the config and textures
+
+let osu_skin = OsuSkin::new(skin_config, Some(textures), None); // last parameter is the sound samples store, which you can import similarly to textures
+```
+
+#### Creating Skins
+
+All skins are loaded in their original formats; Any textures go in ``TextureStore`` or samples go in ``SampleStore``, etc. The config is also preserved so, this next part will talk about dealing with generic skins as creating skins for a specific game differs from one to another.
+
+Additionally all skins can be converting into a generic version of it.
+
+Examples:
+```rust
+OsuSkin::from_generic_mania(&generic); 
+OsuSkin.to_generic_mania();
+```
+```rust
+FluXisSkin::from_generic_mania(&generic); 
+FluXisSkin.to_generic_mania(fluxis_layout); // if you don't have a layout you can just pass None or ().
+```
+
+---
+
+Unlike skins from games not all textures are stored in ``TextureStore``. Skin Elements can have their own textures that are shared pointers (``Option<Arc<RwLock<Texture>>>``). Meaning the texture can be shared anywhere either in a ``TextureStore`` or inside a Skin Element.
+
+#### Exporting Skins
+
+##### Recommened way of exporting a skin
+
+```rust
+export::osu::skin_to_dir(&skin, "path/to/export/to")?;
+export::fluxis::skin_to_dir(&skin, "path/to/export/to")?;
+```
+
+###### Manually exporting a skin
+```rust
+export::osu::ini_to_dir(skin.skin_ini, "path/to/export/to"); // export::{game}
+export::textures_to_dir(skin.textures, "path/to/export/to");
+export::samples_to_dir(skin.samples, "path/to/export/to"); // if you have samples
+```
+
+## JavaScript/TypeScript Usage
+
+### Installation
+For Node.js:
+```sh
+npm install @r2o3/rgskin-nodejs
+```
+
+For web projects:
+```html
+<script src="https://unpkg.com/@r2o3/rgskin-browser@latest/rgskin.js"></script>
+```
+or
+```javascript
+npm install @r2o3/rgskin-browser
+```
+then use as an ES module
+
+### API Reference
+
+#### Initialization
+```javascript
+// For ES modules
+import * as rgskin from '@r2o3/rgskin'; // or if not in node modules use the path to rgskin.js
+
+// or alternatively
+const rgskin = await import('path/to/rgskin.js')
+
+// For CommonJS
+const rgskin = require('rgskin');
+```
+
+you may need to do ``await rgskin.default()`` after importing if you've imported it in a script tag (with type="module") or you get an error like ``Uncaught TypeError: Cannot read properties of undefined (reading '__wbindgen_malloc')``
+
+As of now you can't parse/write using the original structures in JS/TS, will be supported in the *near* future.
+
+#### Importing/Loading Skins
+
+For Node:
+
+##### Recommended way of Loading a skin
+
+```javascript
+const OsuSkin = rgskin.osuSkinFromDir("path/to/skin");
+const FluXisSkin = rgskin.fluXisSkinFromDir("path/to/skin");
+```
+
+##### Manually loading a skin
+
+```javascript
+// create a new texture store, this is where the actual textures will be stored
+let textures = new rgskin.TextureStore();
+
+// you can import textures from a directory like this:
+textures = rgskin.allTexturesFromDir("path/to/skin");
+
+// you can parse configs like this:
+let raw_str = rgskin.iniStrFromDir("path/to/skin")
+let skin_config = rgskin.OsuSkinIni.fromStr(raw_str);
+
+let osuSKin = new rgskin.OsuSkin(skin_config, textures, null) // last parameter is the sound samples store, which you can import similarly to textures
+```
+
+For Browsers:
+
+Unfortunately you can't automatically import everything using a single function.
+So you'll have to do a bit of work. Check [FilesMap preparation](#preparing-the-filesmap)
+
+##### Recommended way of Loading a skin
+
+```javascript
+const OsuSkin = rgskin.osuSkinFromFiles(filesMap);
+const FluXisSkin = rgskin.fluXisSkinFromFiles(filesMap);
+```
+
+##### Manually loading a skin
+
+```javascript
+// create a new texture store, this is where the actual textures will be stored
+let textures = new rgskin.TextureStore();
+
+// you can import textures from files like this:
+// filesMap is a Map object with relative path -> Uint8Array pairs
+textures = rgskin.allTexturesFromFiles(filesMap);
+
+// you can parse configs like this:
+// assuming you have the skin.ini file in your filesMap
+let raw_str = filesMap.get("skin.ini"); // get the Uint8Array
+let decoder = new TextDecoder();
+let ini_string = decoder.decode(raw_str);
+let skin_config = rgskin.OsuSkinIni.fromStr(ini_string);
+
+let osuSkin = new rgskin.OsuSkin(skin_config, textures, null); // last parameter is the sound samples store, which you can import similarly to textures
+```
+
+##### Preparing the filesMap
+
+The `filesMap` parameter is a JavaScript `Map` object where:
+- Keys are filenames (strings)
+- Values are file contents as `Uint8Array`
+
+Example: Reading files from an HTML file input
+
+```javascript
+const filesMap = new Map();
+
+// assuming you have an <input type="file" multiple webkitdirectory> element
+fileInput.addEventListener('change', async (event) => {
+    const files = event.target.files;
+    
+    for (const file of files) {
+        const arrayBuffer = await file.arrayBuffer();
+        const uint8Array = new Uint8Array(arrayBuffer);
+        const relativePath = file.webkitRelativePath || file.name;
+        filesMap.set(relativePath, uint8Array);
+    }
+    
+    // now you can import the skin
+    const skin = rgskin.osuSkinFromFiles(filesMap);
+});
+```
+
+#### Creating Skins
+
+Check [Rust's Creating Skins](#creating-skins) for more details
+
+```javascript
+OsuSkin.fromGenericMania(&generic); 
+OsuSkin.toGenericMania();
+```
+```javascript
+FluXisSkin.fromGenericMania(&generic); 
+FluXisSkin.toGenericMania(fluxis_layout); // if you don't have a layout you can just not pass anything or null.
+```
+
+#### Exporting Skins
+
+For Node:
+
+##### Recommended way of exporting a skin
+
+```javascript
+rgskin.osuSkinToDir(skin, "path/to/export/to");
+rgskin.fluXisSkinToDir(skin, "path/to/export/to");
+```
+
+##### Manually exporting a skin
+
+```javascript
+rgskin.iniToDir(skin.skin_ini, "path/to/export/to");
+rgskin.texturesToDir(skin.textures, "path/to/export/to");
+rgskin.samplesToDir(skin.samples, "path/to/export/to"); // if you have samples
+```
+
+For Browsers:
+
+##### Recommended way of exporting a skin
+
+```javascript
+// Returns a JavaScript Map object with relative path -> Uint8Array pairs
+const filesMap = rgskin.osuSkinToFiles(skin);
+const filesMap = rgskin.fluXisSkinToFiles(skin);
+```
+
+##### Manually exporting a skin
+
+```javascript
+const iniString = rgskin.iniToString(skin.skin_ini);
+const texturesMap = rgskin.texturesToFiles(skin.textures);
+const samplesMap = rgskin.samplesToFiles(skin.samples);
+
+// combine them into a single Map if needed
+const filesMap = new Map([
+    ['skin.ini', new TextEncoder().encode(iniString)],
+    ...texturesMap,
+    ...samplesMap
+]);
+```
+
+Actually Exporting/Downloading the files will depend on your implementation.
+
+Example using JSZip:
+```javascript
+const filesMap = rgskin.osuSkinToFiles(skin);
+
+const zip = new JSZip();
+filesMap.forEach((data, path) => {
+    zip.file(path, data);
+});
+
+const zipBlob = await zip.generateAsync({ type: 'blob' });
+const link = document.createElement('a');
+link.href = URL.createObjectURL(zipBlob);
+link.download = 'skin.zip';
+link.click();
+```
+
+Example Downloading each file indiviually:
+
+```javascript
+const filesMap = rgskin.osuSkinToFiles(skin);
+
+filesMap.forEach((data, path) => {
+    const blob = new Blob([data]);
+    const link = document.createElement('a');
+    link.href = URL.createObjectURL(blob);
+    link.download = path;
+    link.click();
+});
+```
+
+## Building
+
+### Rust Library
+```sh
+cargo build
+```
+
+### WASM Bindings
+1. Install wasm-pack:
+```sh
+cargo install wasm-pack
+```
+> [!IMPORTANT]  
+> It's really recommended to have [wasm-opt](https://github.com/WebAssembly/binaryen) installed and added to path for the wasm build.
+
+2. Build the package:
+```sh
+npm run build # debug build
+npm run build-release # release build
+```
+
+3. This will build it for both node and browser and the output will be in `dist-web` and `dist-node` directory.
+
+## License
+r2o3 uses the MIT License for all its sibiling projects.
+See [LICENSE](https://github.com/r2o3/rgskin/blob/master/LICENSE) for more information

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@r2o3/rgskin-nodejs",
+  "collaborators": [
+    "menvae"
+  ],
+  "description": "A library for converting rhythm game skins.",
+  "version": "0.0.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/r2o3/rgskin"
+  },
+  "files": [
+    "rgskin_bg.wasm",
+    "rgskin.js",
+    "rgskin.d.ts"
+  ],
+  "main": "rgskin.js",
+  "types": "rgskin.d.ts",
+  "keywords": [
+    "wasm",
+    "rust",
+    "rhythm-game",
+    "parser",
+    "converter",
+    "skin"
+  ]
+}

package/rgskin.d.ts

@@ -0,0 +1,316 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class BinaryStore {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor();
+  insertBinary(binary: RawBytes): void;
+  makeUnique(new_path: string, binary: RawBytes): string;
+  loadFromArrayBuffer(path: string, buffer: ArrayBuffer): void;
+  loadFromUint8Array(path: string, array: Uint8Array): void;
+  allLoaded(): boolean;
+  loadedCount(): number;
+  unloadedPaths(): Array<any>;
+  hasBinary(path: string): boolean;
+  getBinaryPath(path: string): string | undefined;
+  binaryHasData(path: string): boolean;
+  getBinaryData(path: string): Uint8Array | undefined;
+  contains(path: string): boolean;
+  remove(path: string): boolean;
+  getLength(): number;
+  isEmpty(): boolean;
+  getPaths(): Array<any>;
+  clear(): void;
+  copy(original_path: string, new_path: string): string | undefined;
+  makeUniqueCopy(original_path: string, new_base_path: string): string | undefined;
+}
+
+export class FluXisKeymode {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  keymode: number;
+  column_width: number;
+  hit_position: number;
+  tint_notes: boolean;
+  tint_lns: boolean;
+  tint_receptors: boolean;
+  colors: string[];
+  receptors_first: boolean;
+  receptor_offset: number;
+}
+
+export class FluXisLayout {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  name: string;
+  author: string;
+}
+
+export class FluXisSkin {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor(skin_json: SkinJson, textures?: TextureStore | null, samples?: BinaryStore | null);
+  toGenericMania(): GenericManiaSkin;
+  toGenericManiaWithLayout(layout: FluXisLayout): GenericManiaSkin;
+  static fromGenericMania(skin: GenericManiaSkin): FluXisSkinWithLayout;
+  getKeymode(keymode: number): FluXisKeymode | undefined;
+  getRequiredTexturePaths(): string[];
+  getRequiredSamplePaths(): string[];
+  skin_json: SkinJson;
+  textures: TextureStore;
+  samples: BinaryStore;
+}
+
+export class FluXisSkinWithLayout {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  skin: FluXisSkin;
+  layout: FluXisLayout;
+}
+
+export class General {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static fromStr(content: string): General;
+  toString(): string;
+  name: string;
+  author: string;
+  version: string;
+  animation_framerate: number;
+  allow_slider_ball_tint: boolean;
+  combo_burst_random: boolean;
+  cursor_centre: boolean;
+  cursor_expand: boolean;
+  cursor_rotate: boolean;
+  cursor_trail_rotate: boolean;
+  custom_combo_burst_sounds: Uint16Array;
+  hit_circle_overlay_above_number: boolean;
+  layered_hit_sounds: boolean;
+  slider_ball_flip: boolean;
+  spinner_fade_playfield: boolean;
+  spinner_frequency_modulate: boolean;
+  spinner_no_blink: boolean;
+}
+
+export class GenericManiaSkin {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  toGenericMania(): GenericManiaSkin;
+  static fromGenericMania(skin: GenericManiaSkin): GenericManiaSkin;
+  getKeymode(keymode: number): Keymode | undefined;
+  getRequiredTexturePaths(): string[];
+  getRequiredSamplePaths(): string[];
+  textures: TextureStore;
+  samples: BinaryStore;
+}
+
+export class Info {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  name: string;
+  creator: string;
+  accent: string;
+}
+
+export class Keymode {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static fromStr(content: string): OsuKeymode;
+  toStr(): string;
+  getTexturePaths(): string[];
+  keymode: number;
+}
+
+export class OsuKeymode {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  keymode: number;
+  keys_under_notes: boolean;
+  judgement_line: boolean;
+  upside_down: boolean;
+  special_style: number;
+  combo_burst_style: number;
+  get split_stages(): boolean | undefined;
+  set split_stages(value: boolean | null | undefined);
+  stage_separation: number;
+  separate_score: boolean;
+  hit_position: number;
+  light_position: number;
+  get score_position(): number | undefined;
+  set score_position(value: number | null | undefined);
+  get combo_position(): number | undefined;
+  set combo_position(value: number | null | undefined);
+  column_start: number;
+  column_right: number;
+  column_line_width: Uint32Array;
+  column_width: Uint32Array;
+  column_spacing: Uint32Array;
+  barline_height: number;
+  lighting_n_width: Uint32Array;
+  lighting_l_width: Uint32Array;
+  get width_for_note_height_scale(): number | undefined;
+  set width_for_note_height_scale(value: number | null | undefined);
+  light_frame_per_second: number;
+  key_flip_when_upside_down: boolean;
+  note_body_style: number;
+  note_body_style_columns: Uint8Array;
+  receptor_images: string[];
+  receptor_images_down: string[];
+  normal_note_images: string[];
+  long_note_head_images: string[];
+  long_note_body_images: string[];
+  long_note_tail_images: string[];
+  stage_left: string;
+  stage_right: string;
+  stage_bottom: string;
+  stage_hint: string;
+  stage_light: string;
+  lighting_n: string;
+  lighting_l: string;
+  warning_arrow: string;
+  hit0: string;
+  hit50: string;
+  hit100: string;
+  hit200: string;
+  hit300: string;
+  hit300g: string;
+}
+
+export class OsuSkin {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor(skin_ini: OsuSkinIni, textures?: TextureStore | null, samples?: BinaryStore | null);
+  toGenericMania(): GenericManiaSkin;
+  static fromGenericMania(skin: GenericManiaSkin): OsuSkin;
+  getKeymode(keymode: number): OsuKeymode | undefined;
+  getRequiredTexturePaths(): string[];
+  getRequiredSamplePaths(): string[];
+  skin_ini: OsuSkinIni;
+  textures: TextureStore;
+  samples: BinaryStore;
+}
+
+export class OsuSkinIni {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor();
+  static fromStr(json_str: string): OsuSkinIni;
+  toString(): string;
+  getRequiredTexturePaths(): string[];
+  getRequiredSamplePaths(): string[];
+  getKeymode(keymode: number): OsuKeymode | undefined;
+  general: General;
+  keymodes: OsuKeymode[];
+}
+
+export class RawBytes {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor(path: string);
+  static fromBytes(path: string, bytes: Uint8Array): RawBytes;
+  getData(): Uint8Array | undefined;
+  static fromArrayBuffer(path: string, buffer: ArrayBuffer): RawBytes;
+  static fromArrayBufferUnloaded(path: string, buffer: ArrayBuffer): RawBytes;
+  static fromUint8Array(path: string, array: Uint8Array): RawBytes;
+  static fromUint8ArrayUnloaded(path: string, array: Uint8Array): RawBytes;
+  getPath(): string;
+  hasData(): boolean;
+  isLoaded(): boolean;
+  isUnloaded(): boolean;
+  isEmpty(): boolean;
+  load(): void;
+  unload(): void;
+  path: string;
+}
+
+export class SkinJson {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor();
+  static fromStr(json_str: string): SkinJson;
+  toString(): string;
+  info: Info;
+  keymodes: FluXisKeymode[];
+}
+
+export class Texture {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor(path: string);
+  static fromBlank(path: string): Texture;
+  static fromArrayBuffer(path: string, buffer: ArrayBuffer): Texture;
+  static fromArrayBufferUnloaded(path: string, buffer: ArrayBuffer): Texture;
+  static fromUint8Array(path: string, array: Uint8Array): Texture;
+  static fromUint8ArrayUnloaded(path: string, array: Uint8Array): Texture;
+  getPath(): string;
+  hasData(): boolean;
+  isLoaded(): boolean;
+  isUnloaded(): boolean;
+  isEmpty(): boolean;
+  load(): void;
+  unload(): void;
+  path: string;
+}
+
+export class TextureStore {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor();
+  insertTexture(texture: Texture): void;
+  makeUnique(new_path: string, texture: Texture): string;
+  loadFromArrayBuffer(path: string, buffer: ArrayBuffer): void;
+  loadFromUint8Array(path: string, array: Uint8Array): void;
+  allLoaded(): boolean;
+  loadedCount(): number;
+  unloadedPaths(): Array<any>;
+  hasTexture(path: string): boolean;
+  getTexturePath(path: string): string | undefined;
+  textureHasData(path: string): boolean;
+  contains(path: string): boolean;
+  remove(path: string): boolean;
+  getLength(): number;
+  isEmpty(): boolean;
+  getPaths(): Array<any>;
+  clear(): void;
+  copy(original_path: string, new_path: string): string | undefined;
+  makeUniqueCopy(original_path: string, new_base_path: string): string | undefined;
+}
+
+export function allSamplesFromDir(path: string): BinaryStore;
+
+export function allTexturesFromDir(path: string): TextureStore;
+
+export function fluXisSkinFromDir(path: string): FluXisSkin;
+
+export function fluXisSkinToDir(skin: FluXisSkin, path: string): void;
+
+export function iniStrFromDir(path: string): string;
+
+export function iniToDir(skin_ini: OsuSkinIni, path: string): void;
+
+export function jsonStrFromDir(path: string): string;
+
+export function jsonToDir(skin_json: SkinJson, path: string): void;
+
+export function layoutToDir(layout_json: FluXisLayout, path: string): void;
+
+export function osuSkinFromDir(path: string): OsuSkin;
+
+export function osuSkinToDir(skin: OsuSkin, path: string): void;
+
+export function samplesFromDir(path: string, relative_sample_paths: Array<any>): BinaryStore;
+
+export function samplesToDir(samples: BinaryStore, path: string): void;
+
+export function texturesFromDir(path: string, relative_texture_paths: Array<any>): TextureStore;
+
+export function texturesToDir(textures: TextureStore, path: string): void;