@textscene/tscn 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vortiago
+
+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

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @textscene/tscn
 
-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.
+`@textscene/tscn` parses Godot `.tscn` scenes. It is the parser of the
+[TextScene Inspector](https://github.com/Vortiago/textscene-inspector), bundled into one ES module
+with no dependency, no peer dependency, no React and no three.js. It runs in Node and in a browser.
+
+The parser reads the current `.tscn` format (`format=3`). The repository's
+[glossary](https://github.com/Vortiago/textscene-inspector/blob/main/GLOSSARY.md) defines the format's terms,
+and [REFERENCES.md](https://github.com/Vortiago/textscene-inspector/blob/main/REFERENCES.md) links Godot's
+format documentation.
+
+## Install
+
+```bash
+npm install @textscene/tscn
+```
+
+## Use
+
+```ts
+import { TscnParser } from '@textscene/tscn';
+
+const scene = new TscnParser().parse(source);
+console.log(scene.nodes[0]?.name);
+```
+
+The package exports `TscnParser` and the types of the scene it returns: `TscnScene`, `TscnNode`,
+`RawNode`, `TscnExternalResource`, `TscnInternalResource` and `TscnMainResource`.
+
+## Licence
+
+MIT. The package ships `LICENSE` and `THIRD-PARTY-NOTICES.md`. The build writes the notices from the
+modules it bundles: the Godot Engine MIT notice covers the Godot code in the parser.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,53 @@
+# Third-party notices
+
+TextScene Inspector is MIT licensed (see `LICENSE`). It additionally contains, and
+distributes, material from the third parties below.
+
+Runtime npm dependencies are not enumerated here; each carries its own licence in its
+published package. FastNoiseLite and the Brotli decoder are the exceptions, since their
+packages keep the licence in a source comment that a bundler strips.
+
+---
+
+## Godot Engine
+
+<https://github.com/godotengine/godot>
+
+TextScene Inspector reproduces Godot's rendering behaviour, and doing that faithfully means
+transcribing engine code rather than approximating it. The files listed below are ports of
+Godot Engine source, used under the MIT licence. Each carries the same notice inline.
+
+### Bundled source
+
+- `packages/textscene-core/src/godot/math/alignment.ts`
+- `packages/textscene-core/src/godot/math/color.ts`
+- `packages/textscene-core/src/godot/math/transform2d.ts`
+- `packages/textscene-core/src/nodes/2d/ui/graphelement/parser.ts`
+- `packages/textscene-core/src/nodes/2d/ui/graphnode/parser.ts`
+- `packages/textscene-core/src/nodes/2d/ui/graphedit/connections.ts`
+- `packages/textscene-core/src/nodes/2d/ui/graphedit/loadOrder.ts`
+
+### Licence
+
+```
+Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md).
+Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.
+
+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/dist/index.d.ts

@@ -0,0 +1,241 @@
+interface Vector3 {
+	x: number;
+	y: number;
+	z: number;
+}
+interface Transform3D {
+	basis_x: Vector3;
+	basis_y: Vector3;
+	basis_z: Vector3;
+	origin: Vector3;
+}
+interface Node3DProperties {
+	/** Node name */
+	name: string;
+	/** Parent node path ("." for root, "NodeName" for named parent) */
+	parent?: string;
+	/** Full transform matrix */
+	transform?: Transform3D;
+	/** Whether this is an instanced scene */
+	instance?: string;
+	/** Child index for editable instance overrides (for example parent="." index="0") */
+	index?: number;
+	/** Whether the node and its subtree are rendered. Defaults to true. */
+	visible?: boolean;
+	/**
+	 * Whether the global transform skips the parent: `global = local` (`node_3d.cpp:656-660`).
+	 * Visibility still climbs the parent (`:1132-1143`). Unset when the file omits it.
+	 */
+	top_level?: boolean;
+	/**
+	 * The `visibility_parent` path text, relative to this node. Unset when the file omits it or
+	 * leaves it empty, where the node takes its Node3D parent's visibility parent.
+	 */
+	visibility_parent?: string;
+}
+type OwnerHandOff = symbol;
+type InstanceOwnerFallback = Required<Pick<InstanceNameSetting, "ownerInInstance">> & Pick<InstanceNameSetting, "ownerContentTrail">;
+interface InstanceNameSetting {
+	/**
+	 * The node's path below the instance, ending in its name. A node outside the instance that an
+	 * explicit `owner=` gives to it climbs out with `..`.
+	 */
+	readonly pathInInstance: string;
+	readonly isUnique: boolean;
+	/** An explicit `owner=` below the instance, `''` for the instance itself. Absent: the nearest owner. */
+	readonly ownerInInstance?: string;
+	/**
+	 * The ids of an `owner_uid_path=` that continue inside the node `ownerInInstance` names, which the
+	 * graft follows to the owner (`RawNode.ownerContentTrail`).
+	 */
+	readonly ownerContentTrail?: readonly number[];
+	/**
+	 * The owner to take where the `ownerInInstance` walk finds nothing, from the heading's
+	 * `owner_uid_path=`, in this instance. Absent where the trail names an owner in no instance.
+	 */
+	readonly ownerFallback?: InstanceOwnerFallback;
+	/**
+	 * Set where the `owner_uid_path=` owner sits in another instance: where the `ownerInInstance` walk
+	 * finds nothing, the graft hands this back, and the copy of the setting that awaits it lands there.
+	 */
+	readonly ownerHandOff?: OwnerHandOff;
+	/** Set on that copy: it lands only once the instance its `owner=` walk enters hands this off. */
+	readonly awaits?: OwnerHandOff;
+	/**
+	 * How many of the instance node's children the file seats before the setting lands, its own
+	 * heading included: a host child's `%Name` parent reads the table as of its heading.
+	 */
+	readonly hostChildrenBefore: number;
+}
+/** A parsed scene. `N` is the node the parser built: a `TscnNode`, or the strict parser's `RawNode`. */
+export interface TscnScene<N extends RawNode = TscnNode> {
+	/** Root nodes in the scene tree. */
+	nodes: N[];
+	readonly externalResources: readonly TscnExternalResource[];
+	readonly internalResources: readonly TscnInternalResource[];
+	/**
+	 * Whether Godot gives up on the scene before it re-roots anything, so the builder re-roots no
+	 * orphan, and refuses every scene that instances it. True when the scene has no node, the root
+	 * heading has a `parent=` or states no identifier, a heading spells `parent=""`, or a later
+	 * heading has no `parent=`.
+	 */
+	refusesToInstantiate: boolean;
+	/**
+	 * A `.tres` file's `[gd_resource type=]`, the class the loader builds its `[resource]` body as
+	 * (`resource_format_text.cpp:1166`, `:741`). Absent in a `.tscn`, and where the header names no type.
+	 */
+	resourceType?: string;
+	/**
+	 * The simplified `path=` of each `[editable]` heading, in file order: the instance nodes whose
+	 * content the editor lets the user edit (`resource_format_text.cpp:400`). Absent where none.
+	 */
+	editableInstances?: readonly string[];
+	/**
+	 * A `.tres` file's own `[resource]` body. Absent in a `.tscn`, where the loader refuses the tag
+	 * (`resource_format_text.cpp:723-728`).
+	 */
+	mainResource?: TscnMainResource;
+}
+interface OwnerRecovery {
+	readonly owner: string;
+	readonly ownerContentTrail?: readonly number[];
+}
+/**
+ * The **Raw view** of a node: `rawProperties`, the literals both parsers publish, and no
+ * typed `properties`. The strict parser builds this. A `TscnNode` is a `RawNode`, so a helper
+ * typed on it takes either tree.
+ */
+export interface RawNode {
+	name: string;
+	/** Godot class name, for example "Node3D". */
+	type: string;
+	/** Parent node path: "." for the root's children, "NodeName" for a named parent. */
+	parent?: string;
+	children: RawNode[];
+	/**
+	 * Raw body properties as written, published by both parsers
+	 * (`parser/rawPropertyParity.test.ts`), so read this from code the linter and the
+	 * render path share. It also lets a type-less instance node's overrides be re-parsed
+	 * against the instanced root's type.
+	 */
+	rawProperties: Record<string, string>;
+	/**
+	 * Whether `rawProperties`' key order is one file's scan order (ADR-0035).
+	 * `core/NodeRegistry.ts`'s `parseNodeWithRegistry` sets `true`.
+	 * `resources/layerRawOverride.ts` sets `false`: a shared key keeps the base's
+	 * position but the override's value.
+	 */
+	rawPropertiesOrderReliable?: boolean;
+	/**
+	 * Set when the authored `parent` path descends into instanced content (a `.tscn` or
+	 * `.glb`) this file does not declare: the path below the nearest enclosing instance,
+	 * which holds the node in the tree. Never the empty string. `parent` keeps the
+	 * authored path, so the linter and `mergeInstanceRoot` still read what the file said.
+	 */
+	instanceSubPath?: string;
+	/**
+	 * The name the heading wrote, set only on a tree node the builder re-rooted: its `name`
+	 * is then Godot's rename for the vanished `parent` (`packed_scene.cpp:561-563`).
+	 */
+	authoredName?: string;
+	/**
+	 * True on a tree node the builder seated under the heading its `parent_id_path=` landed on,
+	 * because its `parent` path vanished (`packed_scene.cpp:161-163`). The node keeps its name.
+	 */
+	landedByIdTrail?: true;
+	/**
+	 * On a node seated below the instance heading its `parent_id_path=` enters: the ids that continue in
+	 * that instance's scene. Its graft follows them and places the node (`packed_scene.cpp:1947-2005`).
+	 */
+	parentContentTrail?: readonly number[];
+	/**
+	 * On a node seated below an instance for a `parent=` path into its content, whose `parent_id_path=`
+	 * names a heading of this file: where Godot seats the node should the content lack the path.
+	 * `contentTrail` holds the ids that continue inside that heading, where it is an instance.
+	 */
+	parentTrailFallback?: {
+		readonly path: string;
+		readonly contentTrail?: readonly number[];
+	};
+	/**
+	 * On a node whose `owner_uid_path=` enters an instance: the ids that continue in the scene the node
+	 * at `owner` holds. Where it is set, `owner` names the instance heading, not the owner itself.
+	 */
+	ownerContentTrail?: readonly number[];
+	/**
+	 * On a node whose `owner=` walk enters an instance's content, where it may find nothing, and whose
+	 * `owner_uid_path=` names an owner: the owner Godot takes then (`packed_scene.cpp:159-163`).
+	 */
+	ownerTrailFallback?: OwnerRecovery;
+	/**
+	 * True when the heading declared none of `type=`, `instance=` and
+	 * `instance_placeholder=`: Godot's marker for overriding the node already at this
+	 * path. See `isPropertyOverrideHeading`.
+	 */
+	overridesExistingNode?: boolean;
+	/**
+	 * The heading's `index=`: where Godot moves the node among its parent's children once it adds
+	 * it (`packed_scene.cpp:543-544`). Godot writes it only for a node whose parent comes from an
+	 * instanced scene (`packed_scene.cpp:820-830`). Unset when the heading has none.
+	 */
+	index?: number;
+	/**
+	 * The heading's `owner=` NodePath, root-relative. The loader sets the owner from it
+	 * (resource_format_text.cpp:257-262), which decides the table a `%Name` registers on. Godot's own
+	 * writer never emits it (packed_scene.cpp:1036-1044). A seated node holds it walked from the root
+	 * (`resolvedOwner`): `.` for the root, and each `%Name` the file answers replaced by its claimant.
+	 */
+	owner?: string;
+	/** External scene instance reference, for example ExtResource("1_abc"). */
+	instance?: string;
+	/**
+	 * Set by the seating on an instance node below the root, and on an inherited root: the
+	 * `unique_name_in_owner` settings this file writes inside its content, in file order. The graft
+	 * reads them, and a graft into an outer instance appends the ones it hands down.
+	 */
+	instanceNameSettings?: readonly InstanceNameSetting[];
+}
+/** A node from the lenient parser: the **Raw view** plus the typed values the renderer reads. */
+export interface TscnNode extends RawNode {
+	children: TscnNode[];
+	/** Type-specific properties, for example Node3DProperties for a Node3D. */
+	properties: Node3DProperties | Record<string, unknown>;
+}
+export interface TscnExternalResource {
+	id: string;
+	path: string;
+	type: string;
+	/** The id its own file wrote, on a copy that override re-homing made. The parser never sets it. */
+	authoredId?: string;
+}
+export interface TscnInternalResource {
+	id: string;
+	type: string;
+	data: Record<string, string>;
+	/** The id its own file wrote, on a copy that override re-homing made. The parser never sets it. */
+	authoredId?: string;
+}
+/**
+ * A `.tres` file's `[resource]` body. It has no id and no `type=`: its class is the header's,
+ * {@link TscnScene.resourceType}. `data` holds the raw values, keyed as the scan stores them.
+ */
+export interface TscnMainResource {
+	data: Record<string, string>;
+}
+/**
+ * Lenient TSCN parser used for rendering.
+ *
+ * Strategy: recover from minor errors, log warnings, and keep rendering
+ * whatever it can. For strict validation use `linter/StrictTscnParser`.
+ */
+export declare class TscnParser {
+	private core;
+	/**
+	 * Parse TSCN content. Returns a scene with nodes whose `.properties`
+	 * have been converted from raw snake_case strings to the strongly-typed
+	 * shape declared by the relevant node-type module.
+	 */
+	parse(content: string): TscnScene;
+}
+
+export {};