feat(artifacts): read Godot 3 PCK version 1 archives (#7781)

This commit is contained in:
ShuaixinHuang authored and GitHub committed 2026-10-28 19:43:43 +08:00
1 parent c77735fa83
commit 09225b08e1
6 files changed
+199 -33

No files matched your search

+92 -2
View File
@@ -1,5 +1,6 @@
import {
buildGodotPck,
buildGodotPck1,
buildAliasedGodotPck,
embedGodotPck,
pckU32,
@@ -52,6 +53,95 @@ const members: readonly GodotPckMember[] = [
{ path: "data/é.json", data: '{"session":"Session1"}' },
];
describe("GodotPckArtifactReader format 1", () => {
it.each([false, true])(
"reads Godot 3 format 1 directory and absolute member offsets (embedded=%s)",
async (embedded) => {
const carrier = embedded
? Buffer.from("old Godot engine")
: Buffer.alloc(0);
const pack = buildGodotPck1(members, { carrierBytes: carrier.length });
const bytes = embedded
? Buffer.concat([
carrier,
pack,
pckU64(pack.length),
Buffer.from("GDPC"),
])
: pack;
await withReader(bytes, async (reader) => {
const entries = await list(reader);
expect(entries.map(({ sourcePath }) => sourcePath)).toEqual(
members.map(({ path }) => path),
);
expect(entries.map(({ path }) => path)).toEqual([
"scenes/main.gd",
"project.binary",
"data/é.json",
]);
expect(reader.formatMetadata()).toMatchObject({
format_version: 1,
engine_major: 3,
engine_minor: 5,
embedded,
pack_start: carrier.length,
directory_start: carrier.length + 84,
file_base: 0,
pack_flags: 0,
declared_file_count: members.length,
});
for (const [index, entry] of entries.entries()) {
expect(entry.encrypted).toBe(false);
expect(entry.formatMetadata).toMatchObject({ flags: 0 });
expect(await text(await reader.open(entry))).toBe(
members[index]?.data,
);
}
});
},
);
it("keeps a valid empty Godot 3 format 1 inventory complete", async () => {
await withReader(buildGodotPck1([]), async (reader) => {
expect(await list(reader)).toEqual([]);
expect(reader.formatMetadata()).toMatchObject({
format_version: 1,
directory_status: "available",
declared_file_count: 0,
});
});
});
it.each([
[
"zero-offset removal",
{ path: "gone.gd", data: "", offset: 0n },
"unavailable",
],
[
"out-of-pack data",
{ path: "bad.bin", data: "x", offset: 1n << 40n },
"format",
],
[
"oversized data",
{ path: "bad.bin", data: "x", size: 1n << 40n },
"format",
],
] as const)("refuses Godot 3 format 1 %s", async (_, member, reason) => {
await withReader(buildGodotPck1([member]), async (reader) => {
await expect(list(reader)).rejects.toMatchObject({ reason });
});
});
it("rejects a truncated Godot 3 format 1 directory", async () => {
const pack = buildGodotPck1([{ path: "a.gd", data: "x" }]);
await withReader(pack.subarray(0, 110), async (reader) => {
await expect(list(reader)).rejects.toMatchObject({ reason: "format" });
});
});
});
describe("GodotPckArtifactReader", () => {
it.each([
["format 4 standalone", buildGodotPck(4, members), false],
@@ -186,8 +276,8 @@ describe("GodotPckArtifactReader", () => {
"format",
],
[
"a Godot 3 format 1 pack",
Buffer.concat([Buffer.from("GDPC"), pckU32(1), Buffer.alloc(120)]),
"an unknown format 5 pack",
Buffer.concat([Buffer.from("GDPC"), pckU32(5), Buffer.alloc(120)]),
"unavailable",
],
["bytes without a pack", Buffer.from("not a godot pack at all"), "format"],
+21 -13
View File
@@ -29,7 +29,6 @@ const PACK_DIR_ENCRYPTED = 1;
const PACK_REL_FILEBASE = 2;
const PACK_SPARSE_BUNDLE = 4;
const PACK_FILE_ENCRYPTED = 1;
const MINIMUM_ENTRY_BYTES = 40;
const DIRECTORY_CHUNK_BYTES = 64 * 1024;
/** Encoded retained entry metadata, including escaped paths and source facts. */
const MAX_DIRECTORY_METADATA_BYTES = 64 * 1024 * 1024;
@@ -222,13 +221,19 @@ export class GodotPckArtifactReader implements ArtifactReader {
const offset = await cursor.uint64();
const size = await cursor.uint64();
const md5 = (await cursor.bytes(16)).toString("hex");
const flags = await cursor.uint32();
// Godot 3's format 1 has neither per-file flags nor a file-base field.
const flags = header.format_version === 1 ? 0 : await cursor.uint32();
if ((flags & ~PACK_FILE_ENCRYPTED) !== 0)
throw new ArtifactReaderFailure(
"unavailable",
`Godot patch or unknown member flags are unsupported: 0x${flags.toString(16)}`,
);
const sourcePath = pckMemberPath(rawPath);
if (header.format_version === 1 && offset === 0n)
throw new ArtifactReaderFailure(
"unavailable",
`Godot PCK patch removal entry is unsupported: ${sourcePath}`,
);
const start = toSafeOffset(
offset,
header.file_base,
@@ -329,12 +334,12 @@ const readGodotPckHeader = async (
const fixed = await readArtifactFileBytes(handle, start, 40, end, signal);
const header = readGodotPckHeaderFacts(fixed);
const version = header.formatVersion;
if (![2, 3, 4].includes(version))
if (![1, 2, 3, 4].includes(version))
throw new ArtifactReaderFailure(
"unavailable",
`Godot PCK format ${String(version)} is unsupported; plain formats 2, 3 and 4 are supported`,
`Godot PCK format ${String(version)} is unsupported; plain formats 1, 2, 3 and 4 are supported`,
);
const flags = fixed.readUInt32LE(20);
const flags = version === 1 ? 0 : fixed.readUInt32LE(20);
if (
(flags & ~(PACK_DIR_ENCRYPTED | PACK_REL_FILEBASE | PACK_SPARSE_BUNDLE)) !==
0
@@ -343,16 +348,19 @@ const readGodotPckHeader = async (
"unavailable",
`Godot PCK declares unknown pack flags 0x${flags.toString(16)}`,
);
const fileBase = toSafeOffset(
fixed.readBigUInt64LE(24),
version >= 3 || (flags & PACK_REL_FILEBASE) !== 0 ? start : 0,
end,
"file base",
);
const fileBase =
version === 1
? 0
: toSafeOffset(
fixed.readBigUInt64LE(24),
version >= 3 || (flags & PACK_REL_FILEBASE) !== 0 ? start : 0,
end,
"file base",
);
const directory =
version >= 3
? toSafeOffset(fixed.readBigUInt64LE(32), start, end, "directory")
: start + 96;
: start + (version === 1 ? 84 : 96);
const count = (
await readArtifactFileBytes(handle, directory, 4, end, signal)
).readUInt32LE(0);
@@ -364,7 +372,7 @@ const readGodotPckHeader = async (
: "available";
if (
status === "available" &&
count * MINIMUM_ENTRY_BYTES > end - directory - 4
count * (version === 1 ? 36 : 40) > end - directory - 4
)
throw formatFailure("declared member count cannot fit in the directory");
return {