Skip to content

Latest commit

 

History

History
284 lines (243 loc) · 11.2 KB

api.md

File metadata and controls

284 lines (243 loc) · 11.2 KB
Raw

xnb.js api

This is the usage and API of xnb.js.

Unpacking

unpackToXnbData( file : File/Buffer )

  • file (File / Buffer) : xnb file to unpack
  • Returns : Promise - Fulfills with the unpacked XnbData with headers.

Asynchronously reads the xnb file, and return the data as a object.

// browser usage
document.getElementById("fileInput").addEventlistener(function(){
	const file = this.files[0];
	XNB.unpackToXnbData( file ).then(e=>console.log(e)); // returns XnbData{ header:..., readers:..., content:...}
})
// node.js usage
fs.readFile("./Crobus.xnb")
	.then( unpackToXnbData )
	.then( e=>console.log(e) ); // returns XnbData{ header:..., readers:..., content:...}

unpackToContent( file : File/Buffer )

  • file (File / Buffer) : xnb file to unpack
  • Returns : Promise - Fulfills with the unpacked XnbContent without headers.

Asynchronously reads the xnb file, and return the content data only.

// browser usage
document.getElementById("fileInput").addEventlistener(function(){
	const file = this.files[0];
	XNB.unpackToContent( file ).then(e=>console.log(e)); // returns XnbContent{ type:..., content:...}
})
// node.js usage
fs.readFile("./Crobus.xnb")
	.then( unpackToContent )
	.then( e=>console.log(e) ); // returns XnbContent{ type:..., content:...}

unpackToFiles( file : File/Buffer, config : Object )

  • file (File / Buffer) : xnb file to unpack
  • config (Object) : configs
    • yaml (Boolean) : If true, it returns header file as yaml format. Compatible with XnbExtract.
    • contentOnly (Boolean) : If true, it returns only content files except header data.
    • fileName (String) : The name of the file to return.
  • Returns : Promise - Fullfills with Blob array contains unpacked files.

Asynchronously reads the xnb file, and return the unpacked files array. Text data returns as json format.(yaml format if yaml is true) If both yaml and contentOnly are true, then yaml is ignored. Each element of returned array is an object consisting of {data, extension}. data is the actual data of the unpacked file, either the Blob object (browser) or the Uint8Array (node.js), and extension is the extension of the unpacked file.

// browser usage
document.getElementById("fileInput").addEventlistener(function(){
	const file = this.files[0];
	XNB.unpackToFiles( file ).then(e=>{
		for(let {data, extension} of e)
		{
			console.log(data); // returns Blob()
			console.log(extension); // returns "png", "json", etc...
		}
	});
})
// node.js usage
const fileName = "Crobus.xnb";
const baseName = path.basename(fileName, ".xnb");
fs.readFile(`./${fileName}`)
	.then( e=>XBM.unpackToFiles( file, { fileName:baseName }) )
	.then( e=>{
		for(let {data, extension} of e)
		{
			console.log(data); // returns UInt8Array()
			console.log(extension); // returns "png", "json", etc...
		}
	} );

bufferToXnb( buffer : ArrayBuffer )

  • buffer (ArrayBuffer) : the binary buffer of xnb file
  • Returns : XnbData

Convert buffer of xnb to object with headers.

// browser usage
document.getElementById("fileInput").addEventlistener(function(){
	const file = this.files[0];
	const fileReader = new FileReader();
	fileReader.readAsArrayBuffer(file);
	fileReader.onload = function(){
		const data = XNB.bufferToXnb(this.result); // returns XnbData{ header:..., readers:..., content:...}
	}
})
// node.js usage
const buffer = fs.readFileSync("./Crobus.xnb");
const xnbData = XNB.bufferToXnb(buffer); // returns XnbData{ header:..., readers:..., content:...}

bufferToContents( buffer : ArrayBuffer )

  • buffer (ArrayBuffer) : the binary buffer of xnb file
  • Returns : XnbContent

Convert buffer of xnb to object with only contents.

xnbDataToContent( loadedXnb : XnbData )

  • loadedXnb (XnbData) : the xnb object with header data
  • Returns : XnbContent

Convert XnbData to XnbContent.

xnbDataToFiles( xnbObject : XnbData, config : Object )

  • file (File / Buffer) : xnb file to unpack
  • config (Object) : configs
    • yaml (Boolean) : If true, it returns header file as yaml format. Compatible with XnbExtract.
    • contentOnly (Boolean) : If true, it returns only content files except header data.
    • fileName (String) : The name of the file to return.
  • Returns : Promise - Fullfills with Blob array contains unpacked files.

Convert XnbData to Files array. The format of the array is the same as that of unpackToFiles.

Packing

pack( files : Flielist/Array, configs : Object )

  • files (Filelist/Array) : A array of files to be packed to xnb. Json or yaml file must be included.
  • configs (Object) : configs
    • compression (String) : Compression method. default is "default".
    • debug (Boolean) : If true, it returns the success and failure results of all files.

Receive a list of files to pack and convert them into xnb files. The json or yaml file containing the information in the header must be included. Compatible with XnbExtract. The compression methods currently supported by xnb.js are the following:

  • "default" : Try to use the compression algorithm specified in the header. Files specified as LZ4 compression perform LZ4 compression. Because the LZX compression algorithm is not implemented, files specified as LZX compression are not compressed.
  • "none" : Export the file with uncompressed data.
  • "LZ4" : Use LZ4 compression. Ensure a smaller file size. Exported file is incompatible with XnbExtract because it cannot read xnb files compressed with LZ4.

You can directly put Filelist object in a browser environment. But in a node.js environment, there is no FileList object, so you must put an array whose elements are {name, data} objects as parameters. name means the name of the file and data means the actual binary buffer of the file. To use this in a node.js environment, see the following example:

const files = await readdir(input);
const fileList = [];

// make fileList
for (let name of files)
{
	const readPath = path.resolve(input, name);
	const data = await readFile(readPath);
	fileList.push({name, data});
}

// pack to xnb data
const result = await pack(fileList);
console.log(result);

Reader Plugins

setReaders( readers : Object<BaseReader> )

  • readers (Object<BaseReader>) : Reader

Specifies the type of reader used by xnb.js. This is useful when you want to use only certain readers. The key of readers should be a recognizable data name+Reader for the header of the xnb file, and the value should include the reader class that inherited the BaseReader. See the following example:

import {setReaders} from "@xnb/core";
import {LightweightTexture2DReader, StringReader} from "@xnb/readers";

setReaders({
	Texture2DReader : LightweightTexture2DReader,
	StringReader : StringReader
});

addReaders( readers : Object<BaseReader> )

  • readers (Object<BaseReader>) : Reader

Add the readers used by xnb.js. This is useful when you want to add plugins. See the following example:

import {addReaders} from "xnb";
import {readers as StardewReader} from "@xnb/stardew-valley";

addReaders(StardewReader);

setSchemes( schemes: Object<XNBSchemeObject> )

  • schemes (Object<XNBSchemeObject>) : custom schemes reflects C# class

Specifies the type of scheme used by xnb.js. The key of schemes should be C# class full name, and the value should be custom scheme object. See the following example:

import {setSchemes} from "xnb";

// from StardewValley.GameData.BigCraftables.BigCraftableData C# file
const bigCraftableScheme = {
	Name: "String",
	DisplayName: "String",
	Description: "String",
	Price: "Int32",
	Fragility: "Int32",
	CanBePlacedOutdoors: "Boolean",
	CanBePlacedIndoors: "Boolean",
	IsLamp: "Boolean",
	$Texture: "String",
	SpriteIndex: "Int32",
	$ContextTags: ["String"],
	$CustomFields: {"String": "String"}
};

setSchemes({"StardewValley.GameData.BigCraftables.BigCraftableData": bigCraftableScheme});

addSchemes( schemes: Object<XNBSchemeObject> )

  • schemes (Object<XNBSchemeObject>) : custom schemes reflects C# class

Add the schemes used by xnb.js. See the following example:

import {addSchemes} from "xnb";
import {schemes as StardewSchemes} from "@xnb/stardew-valley";

addSchemes(StardewSchemes);

setEnums( enums: Array<string> )

  • enums (Array<string>) : to read enum full name in C#

Specifies the type of enum full names used by xnb.js. The name should be like StardewValley.Season. See the following example:

import {setEnums} from "xnb";

setEnums(["StardewValley.Season"]);

addEnums( enums: Array<string> )

  • enums (Array<string>) : to read enum full name in C#

Add the type of enum full names used by xnb.js. See the following example:

import {addEnums} from "xnb";

addEnums(["StardewValley.Season"]);

Data Structure

XnbData

XnbData is the object included headers, readers data, and content data extracted from xnb file. unpackToXnbData(), and bufferToXnb() returns this. When unpacking xnb using the library as a worker, you can convert json data into XnbData objects.

XnbData( header : Object, readers : Array, content : Object )

  • header (Object) : Header of xnb
    • target (String) : Target of xnb. It must be 'w', 'm', 'x', 'a', or 'i'
    • formatVersion (Number) : Format version of xnb. It must be 3,4, or 5.
    • hidef (Boolean) : Graphic profile of xnb. If true, it means HiDef, and if false, it means Reach.
    • compressed (Boolean/Number) : Indicates whether xnb is compressed. It can be specified as 128 (LZX compression) or 64 (LZ4 compression).
  • readers (Array) : Reader data of xnb
  • content (Object) : Content data of xnb

Create new XnbData object.

XnbData.prototype.header

Header of xnb.

XnbData.prototype.readers

Reader data of xnb.

XnbData.prototype.content

Content data of xnb.

XnbData.prototype.target readonly

Returns xnb of target platform.

XnbData.prototype.formatVersion readonly

Returns xnb of format version.

XnbData.prototype.hidef readonly

Returns whether xnb is in hiDef mode.

XnbData.prototype.compressed readonly

Returns whether xnb was compressed.

XnbData.prototype.contentType readonly

Returns the content type of xnb. The content type can be one of five:

contentType Description
Texture2D Texture data like sprites, portraits.
TBin Map file.
Effect Effect binary data.
BMFont Font data. This is the xml format.
JSON Object data like item data or dialogue.

XnbData.prototype.rawContent readonly

Returns the actual content of xnb. If XnbData.prototype.content contains export (Texture2D, TBin, Effect, BMFont), it returns a binary of that content; otherwise, it returns json data. Texture2D-type content returns color array that is not compressed in png format.

XnbData.prototype.stringify()

Convert this as stringified json.

XnbContent

XnbContent is an object that contains only content extracted from an Xnb file.

XnbContent.prototype.type

Returns the content type of xnb.

XnbContent.prototype.content

Returns xnb's actual content data in Blob/Uint8Array format. Texture2D-type content returns data compressed in png format. You can use the Blob URL to display an image in a browser environment.