@ritsuwastaken/upackage 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,24 @@
1
+ This is free and unencumbered software released into the public domain.
2
+
3
+ Anyone is free to copy, modify, publish, use, compile, sell, or
4
+ distribute this software, either in source code form or as a compiled
5
+ binary, for any purpose, commercial or non-commercial, and by any
6
+ means.
7
+
8
+ In jurisdictions that recognize copyright laws, the author or authors
9
+ of this software dedicate any and all copyright interest in the
10
+ software to the public domain. We make this dedication for the benefit
11
+ of the public at large and to the detriment of our heirs and
12
+ successors. We intend this dedication to be an overt act of
13
+ relinquishment in perpetuity of all present and future rights to this
14
+ software under copyright law.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19
+ IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20
+ OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22
+ OTHER DEALINGS IN THE SOFTWARE.
23
+
24
+ For more information, please refer to <https://unlicense.org>
package/README.md CHANGED
@@ -1,3 +1,23 @@
1
- # Temporary Holding Version
1
+ # upackage
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Read, edit and write package files of Unreal Engine 1 and 2 games: `.u`, `.utx`, `.uax`, `.ukx`, `.usx`, maps. Versions from 68 to 177.
4
+
5
+ Uses [@ritsuwastaken/farchive](https://github.com/ritsuwastaken/farchive).
6
+
7
+ ## Usage
8
+
9
+ ```bash
10
+ npm install @ritsuwastaken/upackage
11
+ ```
12
+
13
+ ```ts
14
+ import { readFile, writeFile } from "node:fs/promises";
15
+ import { build, className, parse, path, scripts, setScript } from "@ritsuwastaken/upackage";
16
+
17
+ const pkg = parse(await readFile("Engine.u"));
18
+ pkg.exports.forEach((entry, i) => console.log(path(pkg, i + 1), className(pkg, i + 1), entry.data.length));
19
+
20
+ for (const script of scripts(pkg)) console.log(script.class, script.text.length);
21
+ setScript(pkg, "Actor", "class Actor extends Object;\r\n");
22
+ await writeFile("Engine.u", build(pkg));
23
+ ```
@@ -0,0 +1,4 @@
1
+ import { ArchiveError } from "@ritsuwastaken/farchive";
2
+ export declare class PackageError extends ArchiveError {
3
+ constructor(message: string, offset?: number);
4
+ }
package/dist/error.js ADDED
@@ -0,0 +1,7 @@
1
+ import { ArchiveError } from "@ritsuwastaken/farchive";
2
+ export class PackageError extends ArchiveError {
3
+ constructor(message, offset = -1) {
4
+ super(message, offset);
5
+ this.name = "PackageError";
6
+ }
7
+ }
@@ -0,0 +1,4 @@
1
+ export { PackageError } from "./error.ts";
2
+ export { addName, className, findExport, findName, nameOf, objectName, path, readTextBuffer, resolve, writeTextBuffer, type ObjectRef, type TextBuffer } from "./objects.ts";
3
+ export { build, parse, type Export, type Generation, type Import, type Name, type Package } from "./package.ts";
4
+ export { scripts, setScript, stripScripts, type Script } from "./scripts.ts";
package/dist/index.js ADDED
@@ -0,0 +1,4 @@
1
+ export { PackageError } from "./error.js";
2
+ export { addName, className, findExport, findName, nameOf, objectName, path, readTextBuffer, resolve, writeTextBuffer } from "./objects.js";
3
+ export { build, parse } from "./package.js";
4
+ export { scripts, setScript, stripScripts } from "./scripts.js";
@@ -0,0 +1,17 @@
1
+ import type { Export, Import, Package } from "./package.ts";
2
+ export type ObjectRef = number;
3
+ export declare const nameOf: (pkg: Package, index: number) => string;
4
+ export declare const resolve: (pkg: Package, ref: ObjectRef) => Export | Import | null;
5
+ export declare const objectName: (pkg: Package, ref: ObjectRef) => string;
6
+ export declare const className: (pkg: Package, ref: ObjectRef) => string;
7
+ export declare const path: (pkg: Package, ref: ObjectRef) => string;
8
+ export declare const findExport: (pkg: Package, objectPath: string, type?: string) => ObjectRef;
9
+ export declare const findName: (pkg: Package, name: string) => number;
10
+ export declare const addName: (pkg: Package, name: string, flags?: number) => number;
11
+ export interface TextBuffer {
12
+ pos: number;
13
+ top: number;
14
+ text: string;
15
+ }
16
+ export declare const readTextBuffer: (pkg: Package, data: Uint8Array) => TextBuffer;
17
+ export declare const writeTextBuffer: (pkg: Package, value: TextBuffer, original?: Uint8Array) => Uint8Array;
@@ -0,0 +1,77 @@
1
+ import { Reader, Writer } from "@ritsuwastaken/farchive";
2
+ import { PackageError } from "./error.js";
3
+ export const nameOf = (pkg, index) => {
4
+ const entry = pkg.names[index];
5
+ if (!entry)
6
+ throw new PackageError(`Name ${index} is out of range (${pkg.names.length} names)`);
7
+ return entry.name;
8
+ };
9
+ export const resolve = (pkg, ref) => {
10
+ if (ref === 0)
11
+ return null;
12
+ const entry = ref > 0 ? pkg.exports[ref - 1] : pkg.imports[-ref - 1];
13
+ if (!entry)
14
+ throw new PackageError(`Object ${ref} is out of range`);
15
+ return entry;
16
+ };
17
+ export const objectName = (pkg, ref) => {
18
+ const entry = resolve(pkg, ref);
19
+ return entry ? nameOf(pkg, entry.name) : "None";
20
+ };
21
+ export const className = (pkg, ref) => {
22
+ if (ref < 0)
23
+ return nameOf(pkg, pkg.imports[-ref - 1].className);
24
+ const entry = resolve(pkg, ref);
25
+ if (!entry)
26
+ return "None";
27
+ return entry.class === 0 ? "Class" : objectName(pkg, entry.class);
28
+ };
29
+ export const path = (pkg, ref) => {
30
+ const parts = [];
31
+ for (let current = ref, depth = 0; current !== 0 && depth < 64; depth++) {
32
+ const entry = resolve(pkg, current);
33
+ parts.unshift(nameOf(pkg, entry.name));
34
+ current = entry.outer;
35
+ }
36
+ return parts.join(".");
37
+ };
38
+ export const findExport = (pkg, objectPath, type) => {
39
+ const lower = objectPath.toLowerCase();
40
+ for (let i = 0; i < pkg.exports.length; i++) {
41
+ const ref = i + 1;
42
+ if (path(pkg, ref).toLowerCase() === lower && (type === undefined || className(pkg, ref).toLowerCase() === type.toLowerCase()))
43
+ return ref;
44
+ }
45
+ return 0;
46
+ };
47
+ export const findName = (pkg, name) => pkg.names.findIndex((entry) => entry.name.toLowerCase() === name.toLowerCase());
48
+ export const addName = (pkg, name, flags = 0x70010) => {
49
+ const found = findName(pkg, name);
50
+ if (found >= 0)
51
+ return found;
52
+ pkg.names.push({ name, flags });
53
+ return pkg.names.length - 1;
54
+ };
55
+ const isNone = (pkg, index) => nameOf(pkg, index) === "None";
56
+ export const readTextBuffer = (pkg, data) => {
57
+ const reader = new Reader(data);
58
+ if (!isNone(pkg, reader.index()))
59
+ throw new PackageError("TextBuffer has properties, which is not supported");
60
+ const pos = reader.i32();
61
+ const top = reader.i32();
62
+ const text = reader.str();
63
+ if (reader.remaining)
64
+ throw new PackageError(`TextBuffer has ${reader.remaining} unexpected bytes`);
65
+ return { pos, top, text };
66
+ };
67
+ export const writeTextBuffer = (pkg, value, original) => {
68
+ const writer = new Writer();
69
+ const none = original ? new Reader(original).index() : pkg.names.findIndex((entry) => entry.name === "None");
70
+ if (none < 0)
71
+ throw new PackageError("The package has no None name");
72
+ writer.index(none);
73
+ writer.i32(value.pos);
74
+ writer.i32(value.top);
75
+ writer.str(value.text);
76
+ return writer.result();
77
+ };
@@ -0,0 +1,35 @@
1
+ export interface Name {
2
+ name: string;
3
+ flags: number;
4
+ }
5
+ export interface Import {
6
+ classPackage: number;
7
+ className: number;
8
+ outer: number;
9
+ name: number;
10
+ }
11
+ export interface Export {
12
+ class: number;
13
+ super: number;
14
+ outer: number;
15
+ name: number;
16
+ flags: number;
17
+ data: Uint8Array;
18
+ }
19
+ export interface Generation {
20
+ exports: number;
21
+ names: number;
22
+ }
23
+ export interface Package {
24
+ version: number;
25
+ licensee: number;
26
+ flags: number;
27
+ guid: Uint8Array | null;
28
+ generations: Generation[];
29
+ names: Name[];
30
+ imports: Import[];
31
+ exports: Export[];
32
+ trailer: Uint8Array;
33
+ }
34
+ export declare function parse(bytes: Uint8Array): Package;
35
+ export declare function build(pkg: Package): Uint8Array;
@@ -0,0 +1,106 @@
1
+ import { ArchiveError, packageTag, Reader, versions, Writer } from "@ritsuwastaken/farchive";
2
+ import { PackageError } from "./error.js";
3
+ const count = (reader, value, what, at) => {
4
+ if (value < 0 || value > reader.bytes.length)
5
+ throw new PackageError(`Invalid ${what} count ${value}`, at);
6
+ return value;
7
+ };
8
+ export function parse(bytes) {
9
+ try {
10
+ return read(bytes);
11
+ }
12
+ catch (error) {
13
+ if (error instanceof ArchiveError && !(error instanceof PackageError))
14
+ throw new PackageError(error.detail, error.offset);
15
+ throw error;
16
+ }
17
+ }
18
+ function read(bytes) {
19
+ const reader = new Reader(bytes);
20
+ if (reader.u32() !== packageTag)
21
+ throw new PackageError("Not a package file", 0);
22
+ const version = reader.u16();
23
+ const licensee = reader.u16();
24
+ const flags = reader.u32();
25
+ const nameCount = count(reader, reader.i32(), "name", 12);
26
+ const nameOffset = reader.i32();
27
+ const exportCount = count(reader, reader.i32(), "export", 20);
28
+ const exportOffset = reader.i32();
29
+ const importCount = count(reader, reader.i32(), "import", 28);
30
+ const importOffset = reader.i32();
31
+ if (version < 68 || version >= versions.int32Indexes)
32
+ throw new PackageError(`Package version ${version} is not supported`);
33
+ const guid = reader.take(16);
34
+ const generations = Array.from({ length: count(reader, reader.i32(), "generation", reader.offset - 4) }, () => ({ exports: reader.i32(), names: reader.i32() }));
35
+ reader.offset = nameOffset;
36
+ const names = Array.from({ length: nameCount }, () => ({ name: reader.str(), flags: reader.u32() }));
37
+ reader.offset = importOffset;
38
+ const imports = Array.from({ length: importCount }, () => ({ classPackage: reader.index(), className: reader.index(), outer: reader.i32(), name: reader.index() }));
39
+ reader.offset = exportOffset;
40
+ const exports = Array.from({ length: exportCount }, () => {
41
+ const entry = { class: reader.index(), super: reader.index(), outer: reader.i32(), name: reader.index(), flags: reader.u32() };
42
+ const size = reader.index();
43
+ const offset = size > 0 ? reader.index() : 0;
44
+ if (size < 0 || offset < 0 || offset + size > bytes.length)
45
+ throw new PackageError(`Export data out of range (${offset}+${size})`, reader.offset);
46
+ return { ...entry, data: bytes.slice(offset, offset + size) };
47
+ });
48
+ const end = Math.max(reader.offset, importOffset, nameOffset);
49
+ const trailer = bytes.slice(end);
50
+ const check = (index, what) => {
51
+ if (index < 0 || index >= names.length)
52
+ throw new PackageError(`${what} refers to name ${index}, but the package has ${names.length}`);
53
+ };
54
+ imports.forEach((entry, i) => [entry.classPackage, entry.className, entry.name].forEach((index) => check(index, `Import ${i}`)));
55
+ exports.forEach((entry, i) => check(entry.name, `Export ${i}`));
56
+ return { version, licensee, flags, guid, generations, names, imports, exports, trailer };
57
+ }
58
+ export function build(pkg) {
59
+ const writer = new Writer();
60
+ writer.u32(packageTag);
61
+ writer.u16(pkg.version);
62
+ writer.u16(pkg.licensee);
63
+ writer.u32(pkg.flags);
64
+ const at = writer.length;
65
+ for (let i = 0; i < 6; i++)
66
+ writer.i32(0);
67
+ writer.bytes(pkg.guid ?? new Uint8Array(16));
68
+ const generations = pkg.generations.length ? pkg.generations.slice() : [{ exports: 0, names: 0 }];
69
+ generations[generations.length - 1] = { exports: pkg.exports.length, names: pkg.names.length };
70
+ writer.i32(generations.length);
71
+ for (const generation of generations) {
72
+ writer.i32(generation.exports);
73
+ writer.i32(generation.names);
74
+ }
75
+ const nameOffset = writer.length;
76
+ for (const entry of pkg.names) {
77
+ writer.str(entry.name);
78
+ writer.u32(entry.flags);
79
+ }
80
+ const offsets = pkg.exports.map((entry) => {
81
+ const offset = writer.length;
82
+ writer.bytes(entry.data);
83
+ return offset;
84
+ });
85
+ const importOffset = writer.length;
86
+ for (const entry of pkg.imports) {
87
+ writer.index(entry.classPackage);
88
+ writer.index(entry.className);
89
+ writer.i32(entry.outer);
90
+ writer.index(entry.name);
91
+ }
92
+ const exportOffset = writer.length;
93
+ pkg.exports.forEach((entry, i) => {
94
+ writer.index(entry.class);
95
+ writer.index(entry.super);
96
+ writer.i32(entry.outer);
97
+ writer.index(entry.name);
98
+ writer.u32(entry.flags);
99
+ writer.index(entry.data.length);
100
+ if (entry.data.length > 0)
101
+ writer.index(offsets[i]);
102
+ });
103
+ writer.bytes(pkg.trailer);
104
+ [pkg.names.length, nameOffset, pkg.exports.length, exportOffset, pkg.imports.length, importOffset].forEach((value, i) => writer.patchI32(at + i * 4, value));
105
+ return writer.result();
106
+ }
@@ -0,0 +1,9 @@
1
+ import type { Package } from "./package.ts";
2
+ export interface Script {
3
+ class: string;
4
+ path: string;
5
+ text: string;
6
+ }
7
+ export declare function scripts(pkg: Package): Script[];
8
+ export declare function setScript(pkg: Package, classPath: string, text: string): void;
9
+ export declare function stripScripts(pkg: Package): number;
@@ -0,0 +1,32 @@
1
+ import { PackageError } from "./error.js";
2
+ import { className, nameOf, objectName, path, readTextBuffer, writeTextBuffer } from "./objects.js";
3
+ const scriptTexts = (pkg) => pkg.exports.flatMap((entry, i) => {
4
+ const ref = i + 1;
5
+ if (className(pkg, ref) !== "TextBuffer" || nameOf(pkg, entry.name) !== "ScriptText" || entry.outer === 0)
6
+ return [];
7
+ return [{ ref, owner: entry.outer }];
8
+ });
9
+ export function scripts(pkg) {
10
+ return scriptTexts(pkg).map(({ ref, owner }) => ({
11
+ class: objectName(pkg, owner),
12
+ path: path(pkg, owner),
13
+ text: readTextBuffer(pkg, pkg.exports[ref - 1].data).text,
14
+ })).filter((script) => script.text !== "");
15
+ }
16
+ export function setScript(pkg, classPath, text) {
17
+ const lower = classPath.toLowerCase();
18
+ const found = scriptTexts(pkg).find(({ owner }) => path(pkg, owner).toLowerCase() === lower || objectName(pkg, owner).toLowerCase() === lower);
19
+ if (!found)
20
+ throw new PackageError(`No script text for ${classPath}`);
21
+ const entry = pkg.exports[found.ref - 1];
22
+ const current = readTextBuffer(pkg, entry.data);
23
+ entry.data = writeTextBuffer(pkg, { ...current, text }, entry.data);
24
+ }
25
+ export function stripScripts(pkg) {
26
+ const list = scriptTexts(pkg);
27
+ for (const { ref } of list) {
28
+ const entry = pkg.exports[ref - 1];
29
+ entry.data = writeTextBuffer(pkg, { pos: 0, top: 0, text: "" }, entry.data);
30
+ }
31
+ return list.length;
32
+ }
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
- "name": "@ritsuwastaken/upackage",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@ritsuwastaken/upackage",
3
+ "version": "1.0.0",
4
+ "description": "read, edit and write unreal engine 1 and 2 packages",
5
+ "type": "module",
6
+ "sideEffects": false,
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "default": "./dist/index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "dist",
17
+ "README.md"
18
+ ],
19
+ "keywords": [
20
+ "upackage",
21
+ "package",
22
+ "upk",
23
+ "utx",
24
+ "unrealscript",
25
+ "typescript",
26
+ "javascript"
27
+ ],
28
+ "author": "ritsuwastaken",
29
+ "license": "Unlicense",
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git+https://github.com/ritsuwastaken/upackage.git"
33
+ },
34
+ "engines": {
35
+ "node": ">=22"
36
+ },
37
+ "scripts": {
38
+ "build": "tsc -p tsconfig.json",
39
+ "test": "npm run build && node --test \"test/**/*.test.ts\"",
40
+ "prepack": "npm run build"
41
+ },
42
+ "dependencies": {
43
+ "@ritsuwastaken/farchive": "^1.0.2"
44
+ },
45
+ "devDependencies": {
46
+ "@types/node": "^22.20.5",
47
+ "typescript": "7.0.2"
48
+ }
49
+ }