add exports block in package.json, rebrand the package, rename some t…

…ypes and add more documentation

README.md

@@ -95,9 +95,7 @@ const { FTS } = require('arx-convert')
 import fs from 'node:fs'
 import path from 'node:path'
 import { DLF } from 'arx-convert'
-import { ArxDLF } from 'arx-convert/dist/dlf/DLF'
-// types are currently scattered around the project,
-// but a good IDE, like vscode will find the types you're looking for with no issue
+import { ArxDLF } from 'arx-convert/types'
 ;(async () => {
   // reads an unpacked dlf file into a buffer
   const binary = await fs.promises.readFile(path.resolve(__dirname, './level1.dlf.unpacked'))

docs/minimum-arx-level/game/graph/levels/level1/fast.fts.json

@@ -25618,12 +25618,12 @@
         { "x": 0, "y": 0, "z": 1, "u": 1, "v": 0, "llfColorIdx": 2 },
         { "x": 1, "y": 0, "z": 1, "u": 1, "v": 1, "llfColorIdx": 3 }
       ],
-      "tex": 0,
+      "textureContainerId": 0,
       "norm": { "x": 0, "y": -1, "z": 0 },
       "norm2": { "x": 0, "y": 1, "z": 0 },
       "transval": 0,
       "area": 1,
-      "type": 524352,
+      "flags": 524352,
       "room": 1
     }
   ],

package.json

@@ -11,6 +11,20 @@
   "bin": {
     "arx-convert": "dist/bin/convert.js"
   },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./utils": {
+      "default": "./dist/utils.js",
+      "types": "./dist/utils.d.ts"
+    },
+    "./types": {
+      "default": "./dist/types.js",
+      "types": "./dist/types.d.ts"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",

src/common/Color.ts

@@ -3,12 +3,20 @@ import { BinaryIO } from './BinaryIO'
 
 type ColorMode = 'bgra' | 'rgb' | 'abgr'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsFormat.h#L29 */
+/**
+ * Color containing red, green, blue and alpha channels
+ *
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsFormat.h#L29
+ */
 export type ArxColor = {
-  r: number // between 0 and 255
-  g: number // between 0 and 255
-  b: number // between 0 and 255
-  a: number // between 0.0 and 1.0
+  /** red channel, integer between 0 and 255 */
+  r: number
+  /** green channel, integer between 0 and 255 */
+  g: number
+  /** blue channel, integer between 0 and 255 */
+  b: number
+  /** alpha channel, float between 0.0 and 1.0 */
+  a: number
 }
 
 export class Color {

src/common/Light.ts

@@ -3,7 +3,9 @@ import { ArxColor, Color } from './Color'
 import { repeat } from './helpers'
 import { ArxVector3 } from './types'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/Light.h#L80 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/Light.h#L80
+ */
 export enum ArxLightFlags {
   None = 0,
   SemiDynamic = 1 << 0,
@@ -13,14 +15,18 @@ export enum ArxLightFlags {
   SpawnSmoke = 1 << 4,
   Off = 1 << 5,
   ColorLegacy = 1 << 6,
-  NoCasted = 1 << 7, // unused
+  /** unused */
+  NoCasted = 1 << 7,
   FixFlareSize = 1 << 8,
   Fireplace = 1 << 9,
-  NoIgnit = 1 << 10, // block reacting to player casting ignite spell, but douse will still work!
+  /** blocks reacting to player casting ignite spell, but douse will still work! */
+  NoIgnit = 1 << 10,
   Flare = 1 << 11,
 }
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L114 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L114
+ */
 export type ArxLight = {
   pos: ArxVector3
   rgb: ArxColor

src/common/constants.ts

@@ -1,4 +1,8 @@
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsTypes.h#L88 */
+import { TripleOf } from './types'
+
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsTypes.h#L88
+ */
 export enum ArxPolygonFlags {
   None = 0,
   NoShadow = 1 << 0,
@@ -8,7 +12,8 @@ export enum ArxPolygonFlags {
   Glow = 1 << 4,
   Ignore = 1 << 5,
   Quad = 1 << 6,
-  Tiled = 1 << 7, // unused
+  /** unused */
+  Tiled = 1 << 7,
   Metal = 1 << 8,
   Hide = 1 << 9,
   Stone = 1 << 10,
@@ -22,16 +27,24 @@ export enum ArxPolygonFlags {
   NoPath = 1 << 18,
   NoDraw = 1 << 19,
   PrecisePath = 1 << 20,
-  NoClimb = 1 << 21, // unused
-  Angular = 1 << 22, // unused
-  AngularIdx0 = 1 << 23, // unused
-  AngularIdx1 = 1 << 24, // unused
-  AngularIdx2 = 1 << 25, // unused
-  AngularIdx3 = 1 << 26, // unused
+  /** unused */
+  NoClimb = 1 << 21,
+  /** unused */
+  Angular = 1 << 22,
+  /** unused */
+  AngularIdx0 = 1 << 23,
+  /** unused */
+  AngularIdx1 = 1 << 24,
+  /** unused */
+  AngularIdx2 = 1 << 25,
+  /** unused */
+  AngularIdx3 = 1 << 26,
   LateMip = 1 << 27,
 }
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/ai/Paths.h#L65 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/ai/Paths.h#L65
+ */
 export enum ArxZoneFlags {
   None = 0,
   Ambiance = 1 << 1,
@@ -79,7 +92,7 @@ export enum ArxZoneFlags {
 // 0.9999967447916589,
 // 0.9999967447916731,
 
-export const COORDS_THAT_ROUND_UP: [number, number, number][] = [
+export const COORDS_THAT_ROUND_UP: TripleOf<number>[] = [
   [2550, 2600, 2649.999755859375],
   [2649.999755859375, 2700, 2749.999755859375],
   [3949.999755859375, 4000, 4050],

src/common/helpers.ts

@@ -1,6 +1,7 @@
 import { ArxPolygon } from '../fts/Polygon'
 import { ArxVertex } from '../fts/Vertex'
 import { COORDS_THAT_ROUND_UP } from './constants'
+import { QuadrupleOf } from './types'
 
 export const maxAll = (arr: number[]) => {
   let i = arr.length
@@ -17,7 +18,9 @@ export const isZeroVertex = ({ x, y, z }: { x: number; y: number; z: number }) =
   return Math.abs(x) < Number.EPSILON && Math.abs(y) < Number.EPSILON && Math.abs(z) < Number.EPSILON
 }
 
-/** @see https://stackoverflow.com/a/14438954/1806628 */
+/**
+ * @see https://stackoverflow.com/a/14438954/1806628
+ */
 export const uniq = <T>(values: T[]) => {
   return values.filter((value, index, self) => {
     return self.indexOf(value) === index
@@ -54,7 +57,7 @@ export const addLightIndex = (polygons: ArxPolygon[]) => {
   })
 }
 
-export const getCellCoords = ([a, b, c]: [ArxVertex, ArxVertex, ArxVertex, ArxVertex]) => {
+export const getCellCoords = ([a, b, c]: QuadrupleOf<ArxVertex>): [number, number] => {
   const x = (a.x + b.x + c.x) / 3
   const z = (a.z + b.z + c.z) / 3
 

src/common/types.ts

@@ -1,21 +1,31 @@
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsFormat.h#L48 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsFormat.h#L48
+ */
 export type ArxVector3 = {
   x: number
   y: number
   z: number
 }
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsFormat.h#L65 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/GraphicsFormat.h#L65
+ */
 export type ArxRotation = {
   a: number
   b: number
   g: number
 }
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/animation/AnimationFormat.h#L63 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/animation/AnimationFormat.h#L63
+ */
 export type ArxQuaternion = {
   x: number
   y: number
   z: number
   w: number
 }
+
+export type TripleOf<T> = [T, T, T]
+
+export type QuadrupleOf<T> = [T, T, T, T]

src/dlf/DlfHeader.ts

@@ -5,7 +5,9 @@ import { repeat } from '../common/helpers'
 import { ArxRotation, ArxVector3 } from '../common/types'
 import { ArxDLF } from './DLF'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L58 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L58
+ */
 export type ArxDlfHeader = {
   lastUser: string
   time: number

src/dlf/Fog.ts

@@ -4,7 +4,9 @@ import { ArxColor, Color } from '../common/Color'
 import { repeat } from '../common/helpers'
 import { ArxRotation, ArxVector3 } from '../common/types'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L132 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L132
+ */
 export type ArxFog = {
   pos: ArxVector3
   rgb: ArxColor

src/dlf/InteactiveObject.ts

@@ -3,7 +3,9 @@ import { BinaryIO } from '../common/BinaryIO'
 import { repeat } from '../common/helpers'
 import { ArxRotation, ArxVector3 } from '../common/types'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L193 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L193
+ */
 export type ArxInteractiveObject = {
   name: string
   pos: ArxVector3

src/dlf/PathHeader.ts

@@ -4,7 +4,9 @@ import { repeat } from '../common/helpers'
 import { ArxVector3 } from '../common/types'
 import { ArxPath } from './DLF'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L150 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L150
+ */
 export type ArxPathHeader = {
   name: string
   idx: number

src/dlf/Pathway.ts

@@ -3,7 +3,9 @@ import { BinaryIO } from '../common/BinaryIO'
 import { repeat } from '../common/helpers'
 import { ArxVector3 } from '../common/types'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L168 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L168
+ */
 export type ArxPathway = {
   rpos: ArxVector3
   flag: number

src/dlf/Scene.ts

@@ -2,7 +2,9 @@ import { Buffer } from 'node:buffer'
 import { BinaryIO } from '../common/BinaryIO'
 import { repeat } from '../common/helpers'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L88 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/scene/LevelFormat.h#L88
+ */
 export type ArxScene = {
   levelIdx: number
 }

src/fts/AnchorData.ts

@@ -3,7 +3,9 @@ import { BinaryIO } from '../common/BinaryIO'
 import { ArxVector3 } from '../common/types'
 import { ArxAnchor } from './Anchor'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/data/FastSceneFormat.h#L117 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/data/FastSceneFormat.h#L117
+ */
 export type ArxAnchorData = {
   pos: ArxVector3
   radius: number

src/fts/EPData.ts

@@ -1,20 +1,25 @@
 import { Buffer } from 'node:buffer'
 import { BinaryIO } from '../common/BinaryIO'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/data/FastSceneFormat.h#L161 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/data/FastSceneFormat.h#L161
+ */
 export type ArxEPData = {
-  px: number
-  py: number
-  idx: number
+  cellX: number
+  cellY: number
+  /**
+   * this number is a counter for polygons in the cell, it has no relation to the order of polygons globally
+   */
+  polygonIdx: number
 }
 
 export class EPData {
   static readFrom(binary: BinaryIO): ArxEPData {
     const [px, py, idx] = binary.readInt16Array(4)
-    return { px, py, idx }
+    return { cellX: px, cellY: py, polygonIdx: idx }
   }
 
-  static accumulateFrom({ px, py, idx }: ArxEPData) {
+  static accumulateFrom({ cellX: px, cellY: py, polygonIdx: idx }: ArxEPData) {
     const buffer = Buffer.alloc(EPData.sizeOf())
     const binary = new BinaryIO(buffer.buffer)
 

src/fts/FtsHeader.ts

@@ -4,7 +4,9 @@ import { FTS_VERSION } from '../common/constants'
 import { repeat } from '../common/helpers'
 import { ArxFTS } from './FTS'
 
-/** @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/data/FastSceneFormat.h#L56 */
+/**
+ * @see https://github.com/arx/ArxLibertatis/blob/1.2.1/src/graphics/data/FastSceneFormat.h#L56
+ */
 export type ArxFtsHeader = {
   levelIdx: number
   numberOfUniqueHeaders: number