HammeriteDataFile

Core: files, names and extension. Inherits RefCounted

Saves and loads a map - or any resource made of Hammerite's own - as data that cannot run code, at any path on disk (#85).

A .res or .tres names the scripts it is made of and can embed one, and loading it runs that script. That is fine for the game's own files and not for a map somebody downloaded, nor can an exported game write under res:// at all. So this file holds values and the NAMES of classes, and a name becomes an object only when the game has said that class may be made from a file (allow_class()). The file never picks a script, and never sets a property the class does not save. A resource the game ships - an icon, a sky model - is written as its res:// path and loaded from there. Anything else that is not one of the allowed classes is refused when saving, rather than dropped from the file.

Properties

Methods

Constants

MAP_EXTENSION

const MAP_EXTENSION = "hmap"

The extension of a saved HammeriteMap, without the dot.

CACHE_EXTENSION

const CACHE_EXTENSION = "hcache"

What is kept beside a map to save work when loading it, such as the compiled worldrep: another extension so that it is not offered where a map is asked for.

PREFAB_SET_EXTENSION

const PREFAB_SET_EXTENSION = "hprefabs"

The extension of a saved HammeritePrefabSet, without the dot.

VERSION

const VERSION = 1

The container format this writes. A file of a higher one is refused; a class's own versions are version_of().

Property descriptions

last_error

var last_error: String = ""

Why the last read() or write() failed, for whoever has to tell the author.

last_warnings

var last_warnings: PackedStringArray = PackedStringArray()

What the last read() or from_text() did not take as it was, though it read the file: classes this game does not have, carried rather than read (HammeriteUnknownData), and properties a class no longer saves, dropped.

Method descriptions

allow_class()

static func allow_class(name: StringName) -> void

Let name - a script's class_name - be made from a data file. Core's own classes are allowed already; an addon or a game adds whatever it keeps on a map, such as a baked graph in HammeriteMap.custom_data.

add_upgrade()

static func add_upgrade(name: StringName, upgrade: Callable) -> void

Say how name's values, as written by its current version, become the next version's. The class is then one version newer (version_of()), files record it, and a file written before goes through upgrade as it is read - and every later upgrade after it. upgrade is called as upgrade(values) -> Dictionary, on a record's values as the file holds them, before any object is made: plain values read and written with upgrade_get() and upgrade_set(), a reference as a mark to move rather than read. Register before the first file is read, where allow_class() is called. A game's Callable is held in a static, so clear_upgrades() is called on the way out (CLAUDE.md).

add_rename()

static func add_rename(name: StringName, old: StringName, new: StringName) -> void

The commonest upgrade: name's property old is called new now.

upgrade_get()

static func upgrade_get(values: Dictionary, key: String, fallback = null) -> Variant

For an upgrade (add_upgrade()): what values holds under key, read as a plain value - a number, a colour, a string, an array or dictionary of those - or fallback for nothing there, or for a reference to another object in the file, which an upgrade moves rather than reads. A resource the file names by its res:// path comes back loaded.

upgrade_set()

static func upgrade_set(values: Dictionary, key: String, value) -> void

For an upgrade: put plain value in values under key, as the file would have held it, so the reading after the upgrade finds it there. A resource with a res:// path may be among it; an object the file would have to hold itself may not, and is refused.

version_of()

static func version_of(name: StringName) -> int

Which version of name this game writes: 1, and one more for each upgrade registered.

clear_upgrades()

static func clear_upgrades() -> void

Forget every upgrade and rename registered, which drops the Callables a game handed over. The Hammerite autoload calls it on exit.

is_allowed()

static func is_allowed(name: StringName) -> bool

Whether a file may make a name: core's own classes, the few plain engine ones (Image, ImageTexture, Curve, Gradient), and any passed to allow_class().

is_data_path()

static func is_data_path(path: String) -> bool

Whether path names a file in this format rather than one of Godot's.

add_extension()

static func add_extension(extension: String) -> void

Count files ending in extension as data files too - a game's own kinds of content.

write()

static func write(resource: Resource, path: String, text: bool = false, keep_backup: bool = false) -> int

Save resource at path. text writes it as JSON, one property to a line, so content that lives in version control reads as a diff; otherwise it is compressed binary, which is what a map - most of it lightmap pixels - wants. read() tells the two apart by themselves. Written beside the file and moved over it once complete, so a crash or a full disk part way leaves the old file whole. keep_backup keeps the file being replaced as <path>.bak. A map records who provides what it names as it is saved (HammeriteReferences.record()).

to_text()

static func to_text(resource: Resource) -> String

resource as this format's text, for somewhere that is not a file - the clipboard. Empty, with last_error saying why, when something in it is not allowed.

from_text()

static func from_text(text: String) -> Resource

The resource text holds, read with every check read() makes - it is text from anywhere - or null, with last_error saying why.

read()

static func read(path: String) -> Resource

The resource saved at path, or null - with last_error saying why - when it is missing, is not this format, or names a class the game has not allowed. A new resource on every call, with Resource.resource_path taken over as path. A HammeriteMap comes back rewired (HammeriteMap.rewire_objects()), ready to use. Reads in flight on several threads at once share last_error and last_warnings; ask read_report() instead there.

read_report()

static func read_report(path: String) -> HammeriteDataFile.ReadReport

read(), answering with its error and its warnings rather than through the shared statics, and pushing no error: for a read on a worker, or two at once.

unknown_classes()

static func unknown_classes(root: Resource) -> PackedStringArray

The classes this game does not have that root carries (HammeriteUnknownData), each once and sorted: what a tool says before a map is saved, or lists as the addons a map was made with. Asked of what root holds now, so it is right after edits as well as after a read - which means walking all of it, a couple of seconds for a large baked level: ask before a save, not often.

class ReadReport

What read_report() answers with: the resource, or why there is none, and what was read other than as the file had it.

Properties

Property descriptions

resource

var resource: Resource = null

What was read, or null.

error

var error: String = ""

Why nothing was read, or empty.

warnings

var warnings: PackedStringArray = PackedStringArray()

What was not taken as it was, though the file was read: see HammeriteDataFile.last_warnings.