From 80c4caa82b918f7c2b00c54b410ef3c42fdec574 Mon Sep 17 00:00:00 2001 From: Frotty <1486037+Frotty@users.noreply.github.com> Date: Mon, 17 Aug 2026 07:08:43 +0000 Subject: [PATCH] docs(stdlib): regenerate API reference --- _data/stdlib_index.json | 2250 ++++++++++++++--- _doc/stdlib/ref/_wurst/Annotations.md | 11 + _doc/stdlib/ref/_wurst/MagicFunctions.md | 84 + _doc/stdlib/ref/data/IntMap.md | 27 + .../ref/file/StructuredSerialization.md | 241 ++ .../ref/file/StructuredSerializationCore.md | 182 ++ _doc/stdlib/ref/index.md | 5 +- 7 files changed, 2486 insertions(+), 314 deletions(-) create mode 100644 _doc/stdlib/ref/data/IntMap.md create mode 100644 _doc/stdlib/ref/file/StructuredSerialization.md create mode 100644 _doc/stdlib/ref/file/StructuredSerializationCore.md diff --git a/_data/stdlib_index.json b/_data/stdlib_index.json index 8cb0fcc..71402c3 100644 --- a/_data/stdlib_index.json +++ b/_data/stdlib_index.json @@ -112352,6 +112352,37 @@ } ] }, + { + "package": "IntMap", + "category": "data", + "categoryLabel": "Data Structures", + "sourcePath": "wurst/data/IntMap.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/data/IntMap.wurst", + "summary": "O(1) integer-keyed map with compiler-specialized value storage.\n\nJASS hashtables use integer child keys, so fixing the key type avoids an artificial generic\nhash adapter while `V:` keeps strings, reals, booleans, handles, tuples, and class references\nin typed arrays. Removal is unordered. The map does not own stored values.", + "summaryFirstLine": "O(1) integer-keyed map with compiler-specialized value storage.", + "tags": [ + "data" + ], + "imports": [], + "entities": [ + { + "kind": "class", + "name": "IntMap", + "typeParams": "", + "receiver": null, + "signature": "public class IntMap", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 13 + } + ] + }, { "package": "LinkedList", "category": "data", @@ -127389,10 +127420,1684 @@ "members": [ { "kind": "function", - "name": "construct", + "name": "construct", + "typeParams": "", + "receiver": null, + "signature": "construct(string filename)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 45 + }, + { + "kind": "function", + "name": "write", + "typeParams": "", + "receiver": null, + "signature": "function write(player p, string content)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 48 + }, + { + "kind": "function", + "name": "write", + "typeParams": "", + "receiver": null, + "signature": "function write(player p, ChunkedString buffer)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 54 + }, + { + "kind": "function", + "name": "close", + "typeParams": "", + "receiver": null, + "signature": "function close()", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 63 + }, + { + "kind": "function", + "name": "read", + "typeParams": "", + "receiver": null, + "signature": "function read(player p) returns ChunkedString", + "doc": "Reads the file's contents. Only the given player actually reads from\n\t\tdisk; every other client gets an empty ChunkedString, so the result is\n\t\tnot synchronised - see the desync warning at the top of this package.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 69 + }, + { + "kind": "function", + "name": "readAsString", + "typeParams": "", + "receiver": null, + "signature": "function readAsString(player p) returns string", + "doc": "Reads the file's contents as one string. Not synchronised - see read().", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 76 + } + ], + "enumMembers": [], + "line": 42 + } + ] + }, + { + "package": "GameStatus", + "category": "file", + "categoryLabel": "File & Network", + "sourcePath": "wurst/file/GameStatus.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/GameStatus.wurst", + "summary": "", + "summaryFirstLine": "", + "tags": [ + "file" + ], + "imports": [], + "entities": [ + { + "kind": "enum", + "name": "GameStatus", + "typeParams": "", + "receiver": null, + "signature": "public enum GameStatus", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 3 + } + ] + }, + { + "package": "MultibyteDiagnostics", + "category": "file", + "categoryLabel": "File & Network", + "sourcePath": "wurst/file/MultibyteDiagnostics.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/MultibyteDiagnostics.wurst", + "summary": "", + "summaryFirstLine": "", + "tags": [ + "file" + ], + "imports": [], + "entities": [ + { + "kind": "function", + "name": "runMultibyteDiagnostics", + "typeParams": "", + "receiver": null, + "signature": "public function runMultibyteDiagnostics()", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 41 + } + ] + }, + { + "package": "SaveLoadData", + "category": "file", + "categoryLabel": "File & Network", + "sourcePath": "wurst/file/SaveLoadData.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/SaveLoadData.wurst", + "summary": "Asynchronously loads the data from the file of the given player\n\tand then synchronizes it with all other players.\n\tThe listener will be invoked with the synced data string.", + "summaryFirstLine": "Asynchronously loads the data from the file of the given player", + "tags": [ + "file" + ], + "imports": [ + "FileIO" + ], + "entities": [ + { + "kind": "constant", + "name": "READ_FILES_IN_REPLAYS", + "typeParams": "", + "receiver": null, + "signature": "public constant READ_FILES_IN_REPLAYS = false", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": true, + "members": [], + "enumMembers": [], + "line": 25 + }, + { + "kind": "extension-function", + "name": "toString", + "typeParams": "", + "receiver": "LoadStatus", + "signature": "public function LoadStatus.toString() returns string", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 27 + }, + { + "kind": "enum", + "name": "LoadStatus", + "typeParams": "", + "receiver": null, + "signature": "public enum LoadStatus", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [ + "SUCCESS", + "FAIL_PLAYER_OFFLINE", + "FAIL_FILE_EMPTY", + "FAIL_CANT_READ" + ], + "line": 38 + }, + { + "kind": "extension-function", + "name": "isFail", + "typeParams": "", + "receiver": "LoadStatus", + "signature": "public function LoadStatus.isFail() returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 44 + }, + { + "kind": "interface", + "name": "LoadListener", + "typeParams": "", + "receiver": null, + "signature": "public interface LoadListener", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "onLoad", + "typeParams": "", + "receiver": null, + "signature": "function onLoad(LoadStatus status, ChunkedString data)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 48 + } + ], + "enumMembers": [], + "line": 47 + }, + { + "kind": "extension-function", + "name": "saveData", + "typeParams": "", + "receiver": "player", + "signature": "public function player.saveData(string slotName, string data)", + "doc": "Blockingly saves the given data string for the given player.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 51 + }, + { + "kind": "extension-function", + "name": "saveData", + "typeParams": "", + "receiver": "player", + "signature": "public function player.saveData(string slotName, ChunkedString data)", + "doc": "Blockingly saves the given data string for the given player.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 58 + }, + { + "kind": "extension-function", + "name": "loadData", + "typeParams": "", + "receiver": "player", + "signature": "public function player.loadData(string slotName, LoadListener listener)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 68 + } + ] + }, + { + "package": "Serializable", + "category": "file", + "categoryLabel": "File & Network", + "sourcePath": "wurst/file/Serializable.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/Serializable.wurst", + "summary": "", + "summaryFirstLine": "", + "tags": [ + "file" + ], + "imports": [], + "entities": [ + { + "kind": "class", + "name": "Serializable", + "typeParams": "", + "receiver": null, + "signature": "public abstract class Serializable", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 104 + } + ] + }, + { + "package": "SQLite", + "category": "file", + "categoryLabel": "File & Network", + "sourcePath": "wurst/file/SQLite.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/SQLite.wurst", + "summary": "", + "summaryFirstLine": "", + "tags": [ + "file" + ], + "imports": [], + "entities": [ + { + "kind": "class", + "name": "SqlResult", + "typeParams": "", + "receiver": null, + "signature": "public class SqlResult", + "doc": "A row returned from a SELECT query. Access columns by index via col().", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 52 + }, + { + "kind": "class", + "name": "SqliteDb", + "typeParams": "", + "receiver": null, + "signature": "public class SqliteDb", + "doc": "Wraps an SQLite database connection with convenience methods.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 94 + }, + { + "kind": "constant", + "name": "SQL_DATABASE_PATH", + "typeParams": "", + "receiver": null, + "signature": "public constant SQL_DATABASE_PATH = \":memory:\"", + "doc": "Override this in your package to point at your project database.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": true, + "members": [], + "enumMembers": [], + "line": 235 + }, + { + "kind": "class", + "name": "SQL", + "typeParams": "", + "receiver": null, + "signature": "public class SQL", + "doc": "Singleton database access. Configure the path via SQL_DATABASE_PATH.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 238 + } + ] + }, + { + "package": "StructuredSerialization", + "category": "file", + "categoryLabel": "File & Network", + "sourcePath": "wurst/file/StructuredSerialization.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/StructuredSerialization.wurst", + "summary": "Standard tuple codecs.\n\nField names passed to these codecs are converted by `FieldSerializationWriter` to fixed-width\nnumeric IDs; names are not stored in the save string. Classes and tuples therefore use the same\nwire representation and migration rules. The compiler does not derive persistence IDs from field\nannotations; serialization metadata deliberately remains owned by this library.\n\nCustom tuples need three overloads because tuples cannot implement `FieldSerializable`. The field\nintrinsics keep the codec concise and support mixed component types through overload resolution:\n\n```\ntuple InventorySlot(int itemId, int charges)\n\npublic function FieldSerializationWriter.write(string name, InventorySlot value)\nlet child = new FieldSerializationWriter(1, this.getIntegrityKey())\nwurstForFields(value, (fieldName, fieldValue) -> child.write(fieldName, fieldValue))\nthis.writeObject(name, child)\n\npublic function FieldSerializationReader.read(string name, InventorySlot oldValue) returns InventorySlot\nlet child = this.readObject(name)\nvar result = oldValue\nif child.isValid()\n\twurstMapFields(result, (fieldName, fieldValue) -> fieldValue.readSerializedField(child, fieldName))\ndestroy child\nreturn result\n\npublic function InventorySlot.readSerializedField(FieldSerializationReader reader, string name) returns InventorySlot\nreturn reader.read(name, this)\n\nclass InventoryState implements FieldSerializable\nuse FieldSerializableLifecycle\nInventorySlot slot = InventorySlot(0, 0)\n\noverride function writeSerializedFields(FieldSerializationWriter writer)\n\twurstForFields((fieldName, fieldValue) -> writer.write(fieldName, fieldValue))\n\noverride function readSerializedFields(FieldSerializationReader reader)\n\twurstMapFields((fieldName, fieldValue) -> fieldValue.readSerializedField(reader, fieldName))\n```\n\n`SerializableFields` can automatically use codecs declared by `StructuredSerialization`. For\npackage-local codecs, use `FieldSerializableLifecycle` and keep the two intrinsic mapping methods\nin the same package as the overloads, as above. Nested custom tuples then compose once each tuple\ntype provides the three overloads. Keep component names stable. For tuple-specific schema changes,\nincrement the child writer's schema version and call `child.renameField(oldName, newName)` before\n`wurstMapFields` when reading older versions.", + "summaryFirstLine": "Standard tuple codecs.", + "tags": [ + "file" + ], + "imports": [ + "StructuredSerializationCore" + ], + "entities": [ + { + "kind": "extension-function", + "name": "write", + "typeParams": "", + "receiver": "FieldSerializationWriter", + "signature": "public function FieldSerializationWriter.write(string name, vec2 value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 59 + }, + { + "kind": "extension-function", + "name": "read", + "typeParams": "", + "receiver": "FieldSerializationReader", + "signature": "public function FieldSerializationReader.read(string name, vec2 oldValue) returns vec2", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 65 + }, + { + "kind": "extension-function", + "name": "readSerializedField", + "typeParams": "", + "receiver": "vec2", + "signature": "public function vec2.readSerializedField(FieldSerializationReader reader, string name) returns vec2", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 71 + }, + { + "kind": "extension-function", + "name": "write", + "typeParams": "", + "receiver": "FieldSerializationWriter", + "signature": "public function FieldSerializationWriter.write(string name, vec3 value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 74 + }, + { + "kind": "extension-function", + "name": "read", + "typeParams": "", + "receiver": "FieldSerializationReader", + "signature": "public function FieldSerializationReader.read(string name, vec3 oldValue) returns vec3", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 81 + }, + { + "kind": "extension-function", + "name": "readSerializedField", + "typeParams": "", + "receiver": "vec3", + "signature": "public function vec3.readSerializedField(FieldSerializationReader reader, string name) returns vec3", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 87 + }, + { + "kind": "extension-function", + "name": "write", + "typeParams": "", + "receiver": "FieldSerializationWriter", + "signature": "public function FieldSerializationWriter.write(string name, angle value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 90 + }, + { + "kind": "extension-function", + "name": "read", + "typeParams": "", + "receiver": "FieldSerializationReader", + "signature": "public function FieldSerializationReader.read(string name, angle oldValue) returns angle", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 95 + }, + { + "kind": "extension-function", + "name": "readSerializedField", + "typeParams": "", + "receiver": "angle", + "signature": "public function angle.readSerializedField(FieldSerializationReader reader, string name) returns angle", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 101 + }, + { + "kind": "extension-function", + "name": "write", + "typeParams": "", + "receiver": "FieldSerializationWriter", + "signature": "public function FieldSerializationWriter.write(string name, color value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 104 + }, + { + "kind": "extension-function", + "name": "read", + "typeParams": "", + "receiver": "FieldSerializationReader", + "signature": "public function FieldSerializationReader.read(string name, color oldValue) returns color", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 111 + }, + { + "kind": "extension-function", + "name": "readSerializedField", + "typeParams": "", + "receiver": "color", + "signature": "public function color.readSerializedField(FieldSerializationReader reader, string name) returns color", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 117 + }, + { + "kind": "extension-function", + "name": "write", + "typeParams": "", + "receiver": "FieldSerializationWriter", + "signature": "public function FieldSerializationWriter.write(string name, colorA value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 120 + }, + { + "kind": "extension-function", + "name": "read", + "typeParams": "", + "receiver": "FieldSerializationReader", + "signature": "public function FieldSerializationReader.read(string name, colorA oldValue) returns colorA", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 128 + }, + { + "kind": "extension-function", + "name": "readSerializedField", + "typeParams": "", + "receiver": "colorA", + "signature": "public function colorA.readSerializedField(FieldSerializationReader reader, string name) returns colorA", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 134 + }, + { + "kind": "extension-function", + "name": "write", + "typeParams": "", + "receiver": "FieldSerializationWriter", + "signature": "public function FieldSerializationWriter.write(string name, colorHSV value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 137 + }, + { + "kind": "extension-function", + "name": "read", + "typeParams": "", + "receiver": "FieldSerializationReader", + "signature": "public function FieldSerializationReader.read(string name, colorHSV oldValue) returns colorHSV", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 144 + }, + { + "kind": "extension-function", + "name": "readSerializedField", + "typeParams": "", + "receiver": "colorHSV", + "signature": "public function colorHSV.readSerializedField(FieldSerializationReader reader, string name) returns colorHSV", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 150 + }, + { + "kind": "module", + "name": "FieldSerializableLifecycle", + "typeParams": "", + "receiver": null, + "signature": "public module FieldSerializableLifecycle", + "doc": "Shared typed lifecycle for `FieldSerializable` classes that provide their own field mapping.\n\nPrefer `SerializableFields` when all field codecs come from `StructuredSerialization`. Use this\nmodule when mapping fields in the class package is necessary, notably for package-local tuple\ncodecs. Implement `writeSerializedFields` and `readSerializedFields`; serialization, integrity,\nmigration, nested-object loading, and typed `load` remain provided here.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "writeSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "abstract function writeSerializedFields(FieldSerializationWriter writer)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 162 + }, + { + "kind": "function", + "name": "readSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "abstract function readSerializedFields(FieldSerializationReader reader)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 163 + }, + { + "kind": "function", + "name": "readSerializedField", + "typeParams": "", + "receiver": null, + "signature": "function readSerializedField(FieldSerializationReader reader, string name) returns thistype", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 165 + }, + { + "kind": "function", + "name": "serialize", + "typeParams": "", + "receiver": null, + "signature": "function serialize() returns ChunkedString", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 172 + }, + { + "kind": "function", + "name": "serialize", + "typeParams": "", + "receiver": null, + "signature": "function serialize(int schemaVersion) returns ChunkedString", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 175 + }, + { + "kind": "function", + "name": "serialize", + "typeParams": "", + "receiver": null, + "signature": "function serialize(int schemaVersion, int integrityKey) returns ChunkedString", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 178 + }, + { + "kind": "function", + "name": "deserialize", + "typeParams": "", + "receiver": null, + "signature": "function deserialize(ChunkedString input) returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 185 + }, + { + "kind": "function", + "name": "deserialize", + "typeParams": "", + "receiver": null, + "signature": "function deserialize(ChunkedString input, int integrityKey) returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 188 + }, + { + "kind": "function", + "name": "deserialize", + "typeParams": "", + "receiver": null, + "signature": "function deserialize(ChunkedString input, int integrityKey, SerializationMigration migration) returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 191 + }, + { + "kind": "function", + "name": "load", + "typeParams": "", + "receiver": null, + "signature": "function load(ChunkedString input) returns thistype", + "doc": "Loads valid data into this instance and returns it for concise construction and chaining.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 201 + } + ], + "enumMembers": [], + "line": 161 + }, + { + "kind": "module", + "name": "SerializableFieldMapping", + "typeParams": "", + "receiver": null, + "signature": "public module SerializableFieldMapping", + "doc": "Automatic field mapping without adding a second `serialize`/`deserialize` lifecycle.\n\nUse this during a compatibility window when a data class still extends legacy `Serializable`, or\nwhen another base class already owns lifecycle methods. The class must implement `FieldSerializable`.\nAll of its accessible mutable instance fields participate; keep runtime-only state in a separate\nclass because persisted-field annotation filtering is not available.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "writeSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "function writeSerializedFields(FieldSerializationWriter writer)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 214 + }, + { + "kind": "function", + "name": "readSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "function readSerializedFields(FieldSerializationReader reader)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 217 + }, + { + "kind": "function", + "name": "readSerializedField", + "typeParams": "", + "receiver": null, + "signature": "function readSerializedField(FieldSerializationReader reader, string name) returns thistype", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 220 + } + ], + "enumMembers": [], + "line": 213 + }, + { + "kind": "module", + "name": "SerializableFields", + "typeParams": "", + "receiver": null, + "signature": "public module SerializableFields", + "doc": "Modern automatic serialization for dedicated state/DAO classes using built-in codecs.\n\nAdd `implements FieldSerializable` and `use SerializableFields`. The compiler expands field\niteration to direct accesses. The tagged format tolerates field reordering, added/removed fields,\nand unknown future wire types. Missing fields retain constructor defaults. Use a schema version and\n`SerializationMigration` for semantic changes or `renameField` for renamed attributes. For custom\ntuple codecs declared in the consuming package, use `FieldSerializableLifecycle` as documented\nabove so overload resolution occurs where those codecs are visible. Classes that must also retain\nlegacy `Serializable` should use `SerializableFieldMapping` to avoid conflicting lifecycle methods.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "writeSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "override function writeSerializedFields(FieldSerializationWriter writer)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 241 + }, + { + "kind": "function", + "name": "readSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "override function readSerializedFields(FieldSerializationReader reader)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 245 + } + ], + "enumMembers": [], + "line": 238 + } + ] + }, + { + "package": "StructuredSerializationCore", + "category": "file", + "categoryLabel": "File & Network", + "sourcePath": "wurst/file/StructuredSerializationCore.wurst", + "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/StructuredSerializationCore.wurst", + "summary": "Default integrity key for structured saves. Override this in map configuration with a private,\nmap-specific value. It is intended to deter edited player save codes, not provide cryptographic\nauthentication against somebody who can inspect the map script.", + "summaryFirstLine": "Default integrity key for structured saves. Override this in map configuration with a private,", + "tags": [ + "file" + ], + "imports": [], + "entities": [ + { + "kind": "constant", + "name": "SERIALIZATION_FORMAT_VERSION", + "typeParams": "", + "receiver": null, + "signature": "public constant SERIALIZATION_FORMAT_VERSION = 2", + "doc": "Current tagged serialization wire format.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 8 + }, + { + "kind": "constant", + "name": "SERIALIZATION_INTEGRITY_KEY", + "typeParams": "", + "receiver": null, + "signature": "public constant SERIALIZATION_INTEGRITY_KEY = 0x6D2B79F5", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": true, + "members": [], + "enumMembers": [], + "line": 15 + }, + { + "kind": "constant", + "name": "SERIALIZATION_REAL_DECIMALS", + "typeParams": "", + "receiver": null, + "signature": "public constant SERIALIZATION_REAL_DECIMALS = 6", + "doc": "Decimal places retained for Jass `real` values. Trailing zeroes are removed on the wire.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": true, + "members": [], + "enumMembers": [], + "line": 18 + }, + { + "kind": "function", + "name": "serializationFieldId", + "typeParams": "", + "receiver": null, + "signature": "public function serializationFieldId(string name) returns int", + "doc": "Returns the stable, case-sensitive numeric ID used for a persisted field name.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 73 + }, + { + "kind": "interface", + "name": "SerializationMigration", + "typeParams": "", + "receiver": null, + "signature": "public interface SerializationMigration", + "doc": "A parsed migration hook. Hooks are invoked but not destroyed by `deserialize`.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "migrate", + "typeParams": "", + "receiver": null, + "signature": "function migrate(FieldSerializationReader reader)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 171 + } + ], + "enumMembers": [], + "line": 170 + }, + { + "kind": "interface", + "name": "FieldSerializable", + "typeParams": "", + "receiver": null, + "signature": "public interface FieldSerializable", + "doc": "Opt-in contract used for recursively serialized class fields.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "writeSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "function writeSerializedFields(FieldSerializationWriter writer)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 175 + }, + { + "kind": "function", + "name": "readSerializedFields", + "typeParams": "", + "receiver": null, + "signature": "function readSerializedFields(FieldSerializationReader reader)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 176 + }, + { + "kind": "function", + "name": "readSerializedField", + "typeParams": "", + "receiver": null, + "signature": "function readSerializedField(FieldSerializationReader reader, string name) returns thistype", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 177 + } + ], + "enumMembers": [], + "line": 174 + }, + { + "kind": "class", + "name": "FieldSerializationWriter", + "typeParams": "", + "receiver": null, + "signature": "public class FieldSerializationWriter", + "doc": "Builds one compact, versioned structured-save envelope.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "construct", + "typeParams": "", + "receiver": null, + "signature": "construct(int schemaVersion)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 186 + }, + { + "kind": "function", + "name": "construct", + "typeParams": "", + "receiver": null, + "signature": "construct(int schemaVersion, int integrityKey)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 189 + }, + { + "kind": "function", + "name": "writeRaw", + "typeParams": "", + "receiver": null, + "signature": "function writeRaw(string name, string token, string payload)", + "doc": "Writes a future-compatible raw field. Custom token values should be one ASCII byte.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 217 + }, + { + "kind": "function", + "name": "writeRaw", + "typeParams": "", + "receiver": null, + "signature": "function writeRaw(string name, string token, ChunkedString payload)", + "doc": "Writes a raw field without flattening its chunked payload. The caller retains ownership.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 222 + }, + { + "kind": "function", + "name": "write", + "typeParams": "", + "receiver": null, + "signature": "function write(string name, int value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 226 + }, + { + "kind": "function", + "name": "write", + "typeParams": "", + "receiver": null, + "signature": "function write(string name, real value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 229 + }, + { + "kind": "function", + "name": "write", + "typeParams": "", + "receiver": null, + "signature": "function write(string name, string value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 232 + }, + { + "kind": "function", + "name": "write", + "typeParams": "", + "receiver": null, + "signature": "function write(string name, boolean value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 235 + }, + { + "kind": "function", + "name": "getIntegrityKey", + "typeParams": "", + "receiver": null, + "signature": "function getIntegrityKey() returns int", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 238 + }, + { + "kind": "function", + "name": "write", + "typeParams": "", + "receiver": null, + "signature": "function write(string name, FieldSerializable value)", + "doc": "Recursively writes an opted-in non-null class instance.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 242 + }, + { + "kind": "function", + "name": "writeObject", + "typeParams": "", + "receiver": null, + "signature": "function writeObject(string name, FieldSerializationWriter child)", + "doc": "Writes and consumes a child writer as a nested class or tuple envelope.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 248 + }, + { + "kind": "function", + "name": "finish", + "typeParams": "", + "receiver": null, + "signature": "function finish() returns ChunkedString", + "doc": "Completes the envelope. The returned value belongs to the caller.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 255 + } + ], + "enumMembers": [], + "line": 180 + }, + { + "kind": "class", + "name": "FieldSerializationReader", + "typeParams": "", + "receiver": null, + "signature": "public class FieldSerializationReader", + "doc": "Parsed field table. Unknown fields and wire tokens are retained and safely skippable.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "construct", + "typeParams": "", + "receiver": null, + "signature": "construct()", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 359 + }, + { + "kind": "function", + "name": "construct", + "typeParams": "", + "receiver": null, + "signature": "construct(ChunkedString input)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 361 + }, + { + "kind": "function", + "name": "construct", + "typeParams": "", + "receiver": null, + "signature": "construct(ChunkedString input, int integrityKey)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 364 + }, + { + "kind": "function", + "name": "isValid", + "typeParams": "", + "receiver": null, + "signature": "function isValid() returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 391 + }, + { + "kind": "function", + "name": "getSchemaVersion", + "typeParams": "", + "receiver": null, + "signature": "function getSchemaVersion() returns int", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 394 + }, + { + "kind": "function", + "name": "getIntegrityKey", + "typeParams": "", + "receiver": null, + "signature": "function getIntegrityKey() returns int", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 397 + }, + { + "kind": "function", + "name": "hasField", + "typeParams": "", + "receiver": null, + "signature": "function hasField(string name) returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 400 + }, + { + "kind": "function", + "name": "hasRaw", + "typeParams": "", + "receiver": null, + "signature": "function hasRaw(string name, string token) returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 403 + }, + { + "kind": "function", + "name": "readRaw", + "typeParams": "", + "receiver": null, + "signature": "function readRaw(string name, string token, string oldValue) returns string", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 407 + }, + { + "kind": "function", + "name": "readRawChunked", + "typeParams": "", + "receiver": null, + "signature": "function readRawChunked(string name, string token) returns ChunkedString", + "doc": "Returns an independent chunked copy of a raw payload, or `null` when the field/token is absent.\nThe caller owns and must destroy the returned value.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 415 + }, + { + "kind": "function", + "name": "read", + "typeParams": "", + "receiver": null, + "signature": "function read(string name, int oldValue) returns int", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 421 + }, + { + "kind": "function", + "name": "read", + "typeParams": "", + "receiver": null, + "signature": "function read(string name, real oldValue) returns real", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 425 + }, + { + "kind": "function", + "name": "read", + "typeParams": "", + "receiver": null, + "signature": "function read(string name, string oldValue) returns string", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 429 + }, + { + "kind": "function", + "name": "read", + "typeParams": "", + "receiver": null, + "signature": "function read(string name, boolean oldValue) returns boolean", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 432 + }, + { + "kind": "function", + "name": "setRaw", "typeParams": "", "receiver": null, - "signature": "construct(string filename)", + "signature": "function setRaw(string name, string token, string payload)", + "doc": "Replaces or creates a decoded field during migration.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 437 + }, + { + "kind": "function", + "name": "set", + "typeParams": "", + "receiver": null, + "signature": "function set(string name, int value)", "doc": "", "deprecated": { "flag": false, @@ -127401,14 +129106,14 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 45 + "line": 449 }, { "kind": "function", - "name": "write", + "name": "set", "typeParams": "", "receiver": null, - "signature": "function write(player p, string content)", + "signature": "function set(string name, real value)", "doc": "", "deprecated": { "flag": false, @@ -127417,14 +129122,14 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 48 + "line": 452 }, { "kind": "function", - "name": "write", + "name": "set", "typeParams": "", "receiver": null, - "signature": "function write(player p, ChunkedString buffer)", + "signature": "function set(string name, string value)", "doc": "", "deprecated": { "flag": false, @@ -127433,14 +129138,14 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 54 + "line": 455 }, { "kind": "function", - "name": "close", + "name": "set", "typeParams": "", "receiver": null, - "signature": "function close()", + "signature": "function set(string name, boolean value)", "doc": "", "deprecated": { "flag": false, @@ -127449,15 +129154,15 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 63 + "line": 458 }, { "kind": "function", - "name": "read", + "name": "removeField", "typeParams": "", "receiver": null, - "signature": "function read(player p) returns ChunkedString", - "doc": "Reads the file's contents. Only the given player actually reads from\n\t\tdisk; every other client gets an empty ChunkedString, so the result is\n\t\tnot synchronised - see the desync warning at the top of this package.", + "signature": "function removeField(string name)", + "doc": "", "deprecated": { "flag": false, "message": null @@ -127465,15 +129170,15 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 69 + "line": 461 }, { "kind": "function", - "name": "readAsString", + "name": "readInto", "typeParams": "", "receiver": null, - "signature": "function readAsString(player p) returns string", - "doc": "Reads the file's contents as one string. Not synchronised - see read().", + "signature": "function readInto(string name, FieldSerializable oldValue) returns boolean", + "doc": "Mutates an existing opted-in child object when a valid nested envelope is present.", "deprecated": { "flag": false, "message": null @@ -127481,180 +129186,15 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 76 - } - ], - "enumMembers": [], - "line": 42 - } - ] - }, - { - "package": "GameStatus", - "category": "file", - "categoryLabel": "File & Network", - "sourcePath": "wurst/file/GameStatus.wurst", - "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/GameStatus.wurst", - "summary": "", - "summaryFirstLine": "", - "tags": [ - "file" - ], - "imports": [], - "entities": [ - { - "kind": "enum", - "name": "GameStatus", - "typeParams": "", - "receiver": null, - "signature": "public enum GameStatus", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 3 - } - ] - }, - { - "package": "MultibyteDiagnostics", - "category": "file", - "categoryLabel": "File & Network", - "sourcePath": "wurst/file/MultibyteDiagnostics.wurst", - "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/MultibyteDiagnostics.wurst", - "summary": "", - "summaryFirstLine": "", - "tags": [ - "file" - ], - "imports": [], - "entities": [ - { - "kind": "function", - "name": "runMultibyteDiagnostics", - "typeParams": "", - "receiver": null, - "signature": "public function runMultibyteDiagnostics()", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 41 - } - ] - }, - { - "package": "SaveLoadData", - "category": "file", - "categoryLabel": "File & Network", - "sourcePath": "wurst/file/SaveLoadData.wurst", - "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/SaveLoadData.wurst", - "summary": "Asynchronously loads the data from the file of the given player\n\tand then synchronizes it with all other players.\n\tThe listener will be invoked with the synced data string.", - "summaryFirstLine": "Asynchronously loads the data from the file of the given player", - "tags": [ - "file" - ], - "imports": [ - "FileIO" - ], - "entities": [ - { - "kind": "constant", - "name": "READ_FILES_IN_REPLAYS", - "typeParams": "", - "receiver": null, - "signature": "public constant READ_FILES_IN_REPLAYS = false", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": true, - "members": [], - "enumMembers": [], - "line": 25 - }, - { - "kind": "extension-function", - "name": "toString", - "typeParams": "", - "receiver": "LoadStatus", - "signature": "public function LoadStatus.toString() returns string", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 27 - }, - { - "kind": "enum", - "name": "LoadStatus", - "typeParams": "", - "receiver": null, - "signature": "public enum LoadStatus", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [ - "SUCCESS", - "FAIL_PLAYER_OFFLINE", - "FAIL_FILE_EMPTY", - "FAIL_CANT_READ" - ], - "line": 38 - }, - { - "kind": "extension-function", - "name": "isFail", - "typeParams": "", - "receiver": "LoadStatus", - "signature": "public function LoadStatus.isFail() returns boolean", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 44 - }, - { - "kind": "interface", - "name": "LoadListener", - "typeParams": "", - "receiver": null, - "signature": "public interface LoadListener", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [ + "line": 469 + }, { "kind": "function", - "name": "onLoad", + "name": "readObject", "typeParams": "", "receiver": null, - "signature": "function onLoad(LoadStatus status, ChunkedString data)", - "doc": "", + "signature": "function readObject(string name) returns FieldSerializationReader", + "doc": "Returns a nested reader borrowed from this reader, or an invalid reader when absent.", "deprecated": { "flag": false, "message": null @@ -127662,19 +129202,35 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 48 + "line": 478 + }, + { + "kind": "function", + "name": "renameField", + "typeParams": "", + "receiver": null, + "signature": "function renameField(string oldName, string newName)", + "doc": "Moves a persisted value from an old field name to a new one. Call this from a migration before\nfield mapping. Existing data under the new name wins, making repeated migrations idempotent.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 488 } ], "enumMembers": [], - "line": 47 + "line": 353 }, { "kind": "extension-function", - "name": "saveData", + "name": "readSerializedField", "typeParams": "", - "receiver": "player", - "signature": "public function player.saveData(string slotName, string data)", - "doc": "Blockingly saves the given data string for the given player.", + "receiver": "int", + "signature": "public function int.readSerializedField(FieldSerializationReader reader, string name) returns int", + "doc": "Type-directed field readers used by the compiler-expanded mapper.", "deprecated": { "flag": false, "message": null @@ -127682,15 +129238,15 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 51 + "line": 510 }, { "kind": "extension-function", - "name": "saveData", + "name": "readSerializedField", "typeParams": "", - "receiver": "player", - "signature": "public function player.saveData(string slotName, ChunkedString data)", - "doc": "Blockingly saves the given data string for the given player.", + "receiver": "real", + "signature": "public function real.readSerializedField(FieldSerializationReader reader, string name) returns real", + "doc": "", "deprecated": { "flag": false, "message": null @@ -127698,45 +129254,14 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 58 + "line": 513 }, { "kind": "extension-function", - "name": "loadData", - "typeParams": "", - "receiver": "player", - "signature": "public function player.loadData(string slotName, LoadListener listener)", - "doc": "", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 68 - } - ] - }, - { - "package": "Serializable", - "category": "file", - "categoryLabel": "File & Network", - "sourcePath": "wurst/file/Serializable.wurst", - "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/Serializable.wurst", - "summary": "", - "summaryFirstLine": "", - "tags": [ - "file" - ], - "imports": [], - "entities": [ - { - "kind": "class", - "name": "Serializable", + "name": "readSerializedField", "typeParams": "", - "receiver": null, - "signature": "public abstract class Serializable", + "receiver": "string", + "signature": "public function string.readSerializedField(FieldSerializationReader reader, string name) returns string", "doc": "", "deprecated": { "flag": false, @@ -127745,78 +129270,15 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 62 - } - ] - }, - { - "package": "SQLite", - "category": "file", - "categoryLabel": "File & Network", - "sourcePath": "wurst/file/SQLite.wurst", - "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/SQLite.wurst", - "summary": "", - "summaryFirstLine": "", - "tags": [ - "file" - ], - "imports": [], - "entities": [ - { - "kind": "class", - "name": "SqlResult", - "typeParams": "", - "receiver": null, - "signature": "public class SqlResult", - "doc": "A row returned from a SELECT query. Access columns by index via col().", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 52 - }, - { - "kind": "class", - "name": "SqliteDb", - "typeParams": "", - "receiver": null, - "signature": "public class SqliteDb", - "doc": "Wraps an SQLite database connection with convenience methods.", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": false, - "members": [], - "enumMembers": [], - "line": 94 - }, - { - "kind": "constant", - "name": "SQL_DATABASE_PATH", - "typeParams": "", - "receiver": null, - "signature": "public constant SQL_DATABASE_PATH = \":memory:\"", - "doc": "Override this in your package to point at your project database.", - "deprecated": { - "flag": false, - "message": null - }, - "configurable": true, - "members": [], - "enumMembers": [], - "line": 235 + "line": 516 }, { - "kind": "class", - "name": "SQL", + "kind": "extension-function", + "name": "readSerializedField", "typeParams": "", - "receiver": null, - "signature": "public class SQL", - "doc": "Singleton database access. Configure the path via SQL_DATABASE_PATH.", + "receiver": "boolean", + "signature": "public function boolean.readSerializedField(FieldSerializationReader reader, string name) returns boolean", + "doc": "", "deprecated": { "flag": false, "message": null @@ -127824,7 +129286,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 238 + "line": 519 } ] }, @@ -157799,8 +159261,8 @@ "categoryLabel": "Core Language", "sourcePath": "wurst/_wurst/Annotations.wurst", "githubUrl": "https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/_wurst/Annotations.wurst", - "summary": "", - "summaryFirstLine": "", + "summary": "Marks a documented declaration whose calls are expanded by the compiler.\n\nUnlike a normal fallback declaration, this does not suppress intrinsic lowering. The declaration\nexists so intrinsic APIs remain visible to completion, navigation, and documentation tools.", + "summaryFirstLine": "Marks a documented declaration whose calls are expanded by the compiler.", "tags": [ "wurst" ], @@ -157886,6 +159348,22 @@ "enumMembers": [], "line": 22 }, + { + "kind": "function", + "name": "compilerintrinsic", + "typeParams": "", + "receiver": null, + "signature": "public function compilerintrinsic()", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 30 + }, { "kind": "function", "name": "configurable", @@ -157900,7 +159378,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 25 + "line": 33 }, { "kind": "function", @@ -157916,7 +159394,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 28 + "line": 36 }, { "kind": "function", @@ -157932,7 +159410,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 31 + "line": 39 }, { "kind": "function", @@ -157948,7 +159426,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 34 + "line": 42 }, { "kind": "function", @@ -157964,7 +159442,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 37 + "line": 45 }, { "kind": "function", @@ -157980,7 +159458,7 @@ "configurable": false, "members": [], "enumMembers": [], - "line": 40 + "line": 48 } ] }, @@ -158715,6 +160193,152 @@ "members": [], "enumMembers": [], "line": 49 + }, + { + "kind": "interface", + "name": "WurstFieldCallback", + "typeParams": "", + "receiver": null, + "signature": "public interface WurstFieldCallback", + "doc": "Tooling signature used by the field-iteration compiler intrinsics.\nThe compiler specializes `value` to the concrete type of each visited field.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "apply", + "typeParams": "", + "receiver": null, + "signature": "function apply(string fieldName, int value)", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 55 + } + ], + "enumMembers": [], + "line": 54 + }, + { + "kind": "interface", + "name": "WurstFieldMapper", + "typeParams": "", + "receiver": null, + "signature": "public interface WurstFieldMapper", + "doc": "Tooling signature used by the field-mapping compiler intrinsic.\nThe compiler specializes both the parameter and result to each concrete field type.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [ + { + "kind": "function", + "name": "apply", + "typeParams": "", + "receiver": null, + "signature": "function apply(string fieldName, int value) returns int", + "doc": "", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 60 + } + ], + "enumMembers": [], + "line": 59 + }, + { + "kind": "function", + "name": "wurstForFields", + "typeParams": "", + "receiver": null, + "signature": "public function wurstForFields(WurstFieldCallback _callback)", + "doc": "Emits the callback once for every accessible non-static field of the enclosing class.\n\nThe callback receives the source field name and its concrete value. This is compile-time code\ngeneration: the generated Jass or Lua contains direct field accesses and no runtime reflection.\nUse the explicit-target form `wurstForFields(target, callback)` for classes and tuples.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 69 + }, + { + "kind": "function", + "name": "wurstForFields", + "typeParams": "", + "receiver": null, + "signature": "public function wurstForFields(T _target, WurstFieldCallback _callback)", + "doc": "Emits the callback once for every accessible non-static field of `target`.\n\nThis overload supports class instances and tuple values. The target expression is evaluated\nonce, and the compiler specializes the callback value to each field's concrete type.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 77 + }, + { + "kind": "function", + "name": "wurstMapFields", + "typeParams": "", + "receiver": null, + "signature": "public function wurstMapFields(WurstFieldMapper _callback)", + "doc": "Maps every accessible mutable non-static field of the enclosing class.\n\nEach callback result is assigned back to its field. Use the explicit-target form\n`wurstMapFields(target, callback)` for classes and tuple variables.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 85 + }, + { + "kind": "function", + "name": "wurstMapFields", + "typeParams": "", + "receiver": null, + "signature": "public function wurstMapFields(T _target, WurstFieldMapper _callback)", + "doc": "Maps every accessible mutable non-static field of `target`.\n\nThis overload supports class instances and tuple variables. The target expression is evaluated\nonce, and each specialized callback result is assigned directly back to its field.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 93 + }, + { + "kind": "function", + "name": "wurstNewInstance", + "typeParams": "", + "receiver": null, + "signature": "public function wurstNewInstance() returns T", + "doc": "Constructs the concrete class `T` through its accessible zero-argument constructor.\n\nThis is an intrinsic rather than runtime reflection. Consequently `T` must be known concretely\nat the call site and normal constructor visibility and abstract-class checks still apply.", + "deprecated": { + "flag": false, + "message": null + }, + "configurable": false, + "members": [], + "enumMembers": [], + "line": 101 } ] }, diff --git a/_doc/stdlib/ref/_wurst/Annotations.md b/_doc/stdlib/ref/_wurst/Annotations.md index 86f8aca..4c59d96 100644 --- a/_doc/stdlib/ref/_wurst/Annotations.md +++ b/_doc/stdlib/ref/_wurst/Annotations.md @@ -10,6 +10,11 @@ generated: true toc: sections --- +Marks a documented declaration whose calls are expanded by the compiler. + +Unlike a normal fallback declaration, this does not suppress intrinsic lowering. The declaration +exists so intrinsic APIs remain visible to completion, navigation, and documentation tools. + **[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/_wurst/Annotations.wurst)** ## Functions @@ -55,6 +60,12 @@ public function compiletimenative() Functions annotated with @compiletimenative are natives that are only available at compiletime, but not ingame. +### compilerintrinsic + +```wurst +public function compilerintrinsic() +``` + ### configurable ```wurst diff --git a/_doc/stdlib/ref/_wurst/MagicFunctions.md b/_doc/stdlib/ref/_wurst/MagicFunctions.md index 0c37fe9..8370d71 100644 --- a/_doc/stdlib/ref/_wurst/MagicFunctions.md +++ b/_doc/stdlib/ref/_wurst/MagicFunctions.md @@ -17,6 +17,34 @@ The called functions must not take any parameters. **[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/_wurst/MagicFunctions.wurst)** +## Interfaces + +### WurstFieldCallback + +```wurst +public interface WurstFieldCallback +``` + +Tooling signature used by the field-iteration compiler intrinsics. +The compiler specializes `value` to the concrete type of each visited field. + +**Members:** + +- `apply(string fieldName, int value)` + +### WurstFieldMapper + +```wurst +public interface WurstFieldMapper +``` + +Tooling signature used by the field-mapping compiler intrinsic. +The compiler specializes both the parameter and result to each concrete field type. + +**Members:** + +- `apply(string fieldName, int value) returns int` + ## Functions ### compileError @@ -75,6 +103,62 @@ public function compiletime(T expr) returns T This is a builtin magic function. * It evaluates it's argument at compiletime and replaces the call with the result. +### wurstForFields + +```wurst +public function wurstForFields(WurstFieldCallback _callback) +``` + +Emits the callback once for every accessible non-static field of the enclosing class. + +The callback receives the source field name and its concrete value. This is compile-time code +generation: the generated Jass or Lua contains direct field accesses and no runtime reflection. +Use the explicit-target form `wurstForFields(target, callback)` for classes and tuples. + +### wurstForFields + +```wurst +public function wurstForFields(T _target, WurstFieldCallback _callback) +``` + +Emits the callback once for every accessible non-static field of `target`. + +This overload supports class instances and tuple values. The target expression is evaluated +once, and the compiler specializes the callback value to each field's concrete type. + +### wurstMapFields + +```wurst +public function wurstMapFields(WurstFieldMapper _callback) +``` + +Maps every accessible mutable non-static field of the enclosing class. + +Each callback result is assigned back to its field. Use the explicit-target form +`wurstMapFields(target, callback)` for classes and tuple variables. + +### wurstMapFields + +```wurst +public function wurstMapFields(T _target, WurstFieldMapper _callback) +``` + +Maps every accessible mutable non-static field of `target`. + +This overload supports class instances and tuple variables. The target expression is evaluated +once, and each specialized callback result is assigned directly back to its field. + +### wurstNewInstance + +```wurst +public function wurstNewInstance() returns T +``` + +Constructs the concrete class `T` through its accessible zero-argument constructor. + +This is an intrinsic rather than runtime reflection. Consequently `T` must be known concretely +at the call site and normal constructor visibility and abstract-class checks still apply. + ## Constants ### compiletime diff --git a/_doc/stdlib/ref/data/IntMap.md b/_doc/stdlib/ref/data/IntMap.md new file mode 100644 index 0000000..54b053b --- /dev/null +++ b/_doc/stdlib/ref/data/IntMap.md @@ -0,0 +1,27 @@ +--- +title: IntMap +layout: stdlibref +category: data +categoryLabel: Data Structures +tags: + - data +source: 'https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/data/IntMap.wurst' +generated: true +toc: sections +--- + +O(1) integer-keyed map with compiler-specialized value storage. + +JASS hashtables use integer child keys, so fixing the key type avoids an artificial generic +hash adapter while `V:` keeps strings, reals, booleans, handles, tuples, and class references +in typed arrays. Removal is unordered. The map does not own stored values. + +**[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/data/IntMap.wurst)** + +## Classes + +### IntMap + +```wurst +public class IntMap +``` diff --git a/_doc/stdlib/ref/file/StructuredSerialization.md b/_doc/stdlib/ref/file/StructuredSerialization.md new file mode 100644 index 0000000..e81b76d --- /dev/null +++ b/_doc/stdlib/ref/file/StructuredSerialization.md @@ -0,0 +1,241 @@ +--- +title: StructuredSerialization +layout: stdlibref +category: file +categoryLabel: File & Network +tags: + - file +source: 'https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/StructuredSerialization.wurst' +generated: true +toc: sections +--- + +Standard tuple codecs. + +Field names passed to these codecs are converted by `FieldSerializationWriter` to fixed-width +numeric IDs; names are not stored in the save string. Classes and tuples therefore use the same +wire representation and migration rules. The compiler does not derive persistence IDs from field +annotations; serialization metadata deliberately remains owned by this library. + +Custom tuples need three overloads because tuples cannot implement `FieldSerializable`. The field +intrinsics keep the codec concise and support mixed component types through overload resolution: + +``` +tuple InventorySlot(int itemId, int charges) + +public function FieldSerializationWriter.write(string name, InventorySlot value) +let child = new FieldSerializationWriter(1, this.getIntegrityKey()) +wurstForFields(value, (fieldName, fieldValue) -> child.write(fieldName, fieldValue)) +this.writeObject(name, child) + +public function FieldSerializationReader.read(string name, InventorySlot oldValue) returns InventorySlot +let child = this.readObject(name) +var result = oldValue +if child.isValid() + wurstMapFields(result, (fieldName, fieldValue) -> fieldValue.readSerializedField(child, fieldName)) +destroy child +return result + +public function InventorySlot.readSerializedField(FieldSerializationReader reader, string name) returns InventorySlot +return reader.read(name, this) + +class InventoryState implements FieldSerializable +use FieldSerializableLifecycle +InventorySlot slot = InventorySlot(0, 0) + +override function writeSerializedFields(FieldSerializationWriter writer) + wurstForFields((fieldName, fieldValue) -> writer.write(fieldName, fieldValue)) + +override function readSerializedFields(FieldSerializationReader reader) + wurstMapFields((fieldName, fieldValue) -> fieldValue.readSerializedField(reader, fieldName)) +``` + +`SerializableFields` can automatically use codecs declared by `StructuredSerialization`. For +package-local codecs, use `FieldSerializableLifecycle` and keep the two intrinsic mapping methods +in the same package as the overloads, as above. Nested custom tuples then compose once each tuple +type provides the three overloads. Keep component names stable. For tuple-specific schema changes, +increment the child writer's schema version and call `child.renameField(oldName, newName)` before +`wurstMapFields` when reading older versions. + +**[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/StructuredSerialization.wurst)** + +**Re-exports:** `StructuredSerializationCore` + +## Modules + +### FieldSerializableLifecycle + +```wurst +public module FieldSerializableLifecycle +``` + +Shared typed lifecycle for `FieldSerializable` classes that provide their own field mapping. + +Prefer `SerializableFields` when all field codecs come from `StructuredSerialization`. Use this +module when mapping fields in the class package is necessary, notably for package-local tuple +codecs. Implement `writeSerializedFields` and `readSerializedFields`; serialization, integrity, +migration, nested-object loading, and typed `load` remain provided here. + +**Members:** + +- `abstract function writeSerializedFields(FieldSerializationWriter writer)` +- `abstract function readSerializedFields(FieldSerializationReader reader)` +- `readSerializedField(FieldSerializationReader reader, string name) returns thistype` +- `serialize() returns ChunkedString` +- `serialize(int schemaVersion) returns ChunkedString` +- `serialize(int schemaVersion, int integrityKey) returns ChunkedString` +- `deserialize(ChunkedString input) returns boolean` +- `deserialize(ChunkedString input, int integrityKey) returns boolean` +- `deserialize(ChunkedString input, int integrityKey, SerializationMigration migration) returns boolean` +- `load(ChunkedString input) returns thistype` + Loads valid data into this instance and returns it for concise construction and chaining. + +### SerializableFieldMapping + +```wurst +public module SerializableFieldMapping +``` + +Automatic field mapping without adding a second `serialize`/`deserialize` lifecycle. + +Use this during a compatibility window when a data class still extends legacy `Serializable`, or +when another base class already owns lifecycle methods. The class must implement `FieldSerializable`. +All of its accessible mutable instance fields participate; keep runtime-only state in a separate +class because persisted-field annotation filtering is not available. + +**Members:** + +- `writeSerializedFields(FieldSerializationWriter writer)` +- `readSerializedFields(FieldSerializationReader reader)` +- `readSerializedField(FieldSerializationReader reader, string name) returns thistype` + +### SerializableFields + +```wurst +public module SerializableFields +``` + +Modern automatic serialization for dedicated state/DAO classes using built-in codecs. + +Add `implements FieldSerializable` and `use SerializableFields`. The compiler expands field +iteration to direct accesses. The tagged format tolerates field reordering, added/removed fields, +and unknown future wire types. Missing fields retain constructor defaults. Use a schema version and +`SerializationMigration` for semantic changes or `renameField` for renamed attributes. For custom +tuple codecs declared in the consuming package, use `FieldSerializableLifecycle` as documented +above so overload resolution occurs where those codecs are visible. Classes that must also retain +legacy `Serializable` should use `SerializableFieldMapping` to avoid conflicting lifecycle methods. + +**Members:** + +- `override function writeSerializedFields(FieldSerializationWriter writer)` +- `override function readSerializedFields(FieldSerializationReader reader)` + +## Extension Functions + +### FieldSerializationWriter.write + +```wurst +public function FieldSerializationWriter.write(string name, vec2 value) +``` + +### FieldSerializationReader.read + +```wurst +public function FieldSerializationReader.read(string name, vec2 oldValue) returns vec2 +``` + +### vec2.readSerializedField + +```wurst +public function vec2.readSerializedField(FieldSerializationReader reader, string name) returns vec2 +``` + +### FieldSerializationWriter.write + +```wurst +public function FieldSerializationWriter.write(string name, vec3 value) +``` + +### FieldSerializationReader.read + +```wurst +public function FieldSerializationReader.read(string name, vec3 oldValue) returns vec3 +``` + +### vec3.readSerializedField + +```wurst +public function vec3.readSerializedField(FieldSerializationReader reader, string name) returns vec3 +``` + +### FieldSerializationWriter.write + +```wurst +public function FieldSerializationWriter.write(string name, angle value) +``` + +### FieldSerializationReader.read + +```wurst +public function FieldSerializationReader.read(string name, angle oldValue) returns angle +``` + +### angle.readSerializedField + +```wurst +public function angle.readSerializedField(FieldSerializationReader reader, string name) returns angle +``` + +### FieldSerializationWriter.write + +```wurst +public function FieldSerializationWriter.write(string name, color value) +``` + +### FieldSerializationReader.read + +```wurst +public function FieldSerializationReader.read(string name, color oldValue) returns color +``` + +### color.readSerializedField + +```wurst +public function color.readSerializedField(FieldSerializationReader reader, string name) returns color +``` + +### FieldSerializationWriter.write + +```wurst +public function FieldSerializationWriter.write(string name, colorA value) +``` + +### FieldSerializationReader.read + +```wurst +public function FieldSerializationReader.read(string name, colorA oldValue) returns colorA +``` + +### colorA.readSerializedField + +```wurst +public function colorA.readSerializedField(FieldSerializationReader reader, string name) returns colorA +``` + +### FieldSerializationWriter.write + +```wurst +public function FieldSerializationWriter.write(string name, colorHSV value) +``` + +### FieldSerializationReader.read + +```wurst +public function FieldSerializationReader.read(string name, colorHSV oldValue) returns colorHSV +``` + +### colorHSV.readSerializedField + +```wurst +public function colorHSV.readSerializedField(FieldSerializationReader reader, string name) returns colorHSV +``` diff --git a/_doc/stdlib/ref/file/StructuredSerializationCore.md b/_doc/stdlib/ref/file/StructuredSerializationCore.md new file mode 100644 index 0000000..4fe310e --- /dev/null +++ b/_doc/stdlib/ref/file/StructuredSerializationCore.md @@ -0,0 +1,182 @@ +--- +title: StructuredSerializationCore +layout: stdlibref +category: file +categoryLabel: File & Network +tags: + - file +source: 'https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/StructuredSerializationCore.wurst' +generated: true +toc: sections +--- + +Default integrity key for structured saves. Override this in map configuration with a private, +map-specific value. It is intended to deter edited player save codes, not provide cryptographic +authentication against somebody who can inspect the map script. + +**[Source on GitHub](https://github.com/wurstscript/WurstStdlib2/blob/master/wurst/file/StructuredSerializationCore.wurst)** + +## Classes + +### FieldSerializationWriter + +```wurst +public class FieldSerializationWriter +``` + +Builds one compact, versioned structured-save envelope. + +**Members:** + +- `construct(int schemaVersion)` +- `construct(int schemaVersion, int integrityKey)` +- `writeRaw(string name, string token, string payload)` + Writes a future-compatible raw field. Custom token values should be one ASCII byte. +- `writeRaw(string name, string token, ChunkedString payload)` + Writes a raw field without flattening its chunked payload. The caller retains ownership. +- `write(string name, int value)` +- `write(string name, real value)` +- `write(string name, string value)` +- `write(string name, boolean value)` +- `getIntegrityKey() returns int` +- `write(string name, FieldSerializable value)` + Recursively writes an opted-in non-null class instance. +- `writeObject(string name, FieldSerializationWriter child)` + Writes and consumes a child writer as a nested class or tuple envelope. +- `finish() returns ChunkedString` + Completes the envelope. The returned value belongs to the caller. + +### FieldSerializationReader + +```wurst +public class FieldSerializationReader +``` + +Parsed field table. Unknown fields and wire tokens are retained and safely skippable. + +**Members:** + +- `construct()` +- `construct(ChunkedString input)` +- `construct(ChunkedString input, int integrityKey)` +- `isValid() returns boolean` +- `getSchemaVersion() returns int` +- `getIntegrityKey() returns int` +- `hasField(string name) returns boolean` +- `hasRaw(string name, string token) returns boolean` +- `readRaw(string name, string token, string oldValue) returns string` +- `readRawChunked(string name, string token) returns ChunkedString` + Returns an independent chunked copy of a raw payload, or `null` when the field/token is absent. + The caller owns and must destroy the returned value. +- `read(string name, int oldValue) returns int` +- `read(string name, real oldValue) returns real` +- `read(string name, string oldValue) returns string` +- `read(string name, boolean oldValue) returns boolean` +- `setRaw(string name, string token, string payload)` + Replaces or creates a decoded field during migration. +- `set(string name, int value)` +- `set(string name, real value)` +- `set(string name, string value)` +- `set(string name, boolean value)` +- `removeField(string name)` +- `readInto(string name, FieldSerializable oldValue) returns boolean` + Mutates an existing opted-in child object when a valid nested envelope is present. +- `readObject(string name) returns FieldSerializationReader` + Returns a nested reader borrowed from this reader, or an invalid reader when absent. +- `renameField(string oldName, string newName)` + Moves a persisted value from an old field name to a new one. Call this from a migration before + field mapping. Existing data under the new name wins, making repeated migrations idempotent. + +## Interfaces + +### SerializationMigration + +```wurst +public interface SerializationMigration +``` + +A parsed migration hook. Hooks are invoked but not destroyed by `deserialize`. + +**Members:** + +- `migrate(FieldSerializationReader reader)` + +### FieldSerializable + +```wurst +public interface FieldSerializable +``` + +Opt-in contract used for recursively serialized class fields. + +**Members:** + +- `writeSerializedFields(FieldSerializationWriter writer)` +- `readSerializedFields(FieldSerializationReader reader)` +- `readSerializedField(FieldSerializationReader reader, string name) returns thistype` + +## Functions + +### serializationFieldId + +```wurst +public function serializationFieldId(string name) returns int +``` + +Returns the stable, case-sensitive numeric ID used for a persisted field name. + +## Extension Functions + +### int.readSerializedField + +```wurst +public function int.readSerializedField(FieldSerializationReader reader, string name) returns int +``` + +Type-directed field readers used by the compiler-expanded mapper. + +### real.readSerializedField + +```wurst +public function real.readSerializedField(FieldSerializationReader reader, string name) returns real +``` + +### string.readSerializedField + +```wurst +public function string.readSerializedField(FieldSerializationReader reader, string name) returns string +``` + +### boolean.readSerializedField + +```wurst +public function boolean.readSerializedField(FieldSerializationReader reader, string name) returns boolean +``` + +## Constants + +### SERIALIZATION_FORMAT_VERSION + +```wurst +public constant SERIALIZATION_FORMAT_VERSION = 2 +``` + +Current tagged serialization wire format. + +### SERIALIZATION_INTEGRITY_KEY + +```wurst +public constant SERIALIZATION_INTEGRITY_KEY = 0x6D2B79F5 +``` + +> 🔧 **Configurable.** Override it in your map's config package. + +### SERIALIZATION_REAL_DECIMALS + +```wurst +public constant SERIALIZATION_REAL_DECIMALS = 6 +``` + +> 🔧 **Configurable.** Override it in your map's config package. + +Decimal places retained for Jass `real` values. Trailing zeroes are removed on the wire. diff --git a/_doc/stdlib/ref/index.md b/_doc/stdlib/ref/index.md index 5cd061c..1d411c0 100644 --- a/_doc/stdlib/ref/index.md +++ b/_doc/stdlib/ref/index.md @@ -36,6 +36,7 @@ If you are choosing a capability, start with the [standard library overview](/st - [HashList](/stdlib/ref/data/HashList.html): HashLists are used if you require quick contains operations - [HashMap](/stdlib/ref/data/HashMap.html): Generic Table Wrapper - [HashSet](/stdlib/ref/data/HashSet.html): Generic set implementation +- [IntMap](/stdlib/ref/data/IntMap.html): O(1) integer-keyed map with compiler-specialized value storage. - [LinkedList](/stdlib/ref/data/LinkedList.html): Doubly-linked list implementation that implements all common list, stack and queue operations. - [LinkedListModule](/stdlib/ref/data/LinkedListModule.html): Turns a class into a linked list where each instance knows it's previous - [PriorityQueue](/stdlib/ref/data/PriorityQueue.html): A binary heap priority queue. @@ -98,6 +99,8 @@ If you are choosing a capability, start with the [standard library overview](/st - [SaveLoadData](/stdlib/ref/file/SaveLoadData.html): Asynchronously loads the data from the file of the given player - [Serializable](/stdlib/ref/file/Serializable.html) - [SQLite](/stdlib/ref/file/SQLite.html) +- [StructuredSerialization](/stdlib/ref/file/StructuredSerialization.html): Standard tuple codecs. +- [StructuredSerializationCore](/stdlib/ref/file/StructuredSerializationCore.html): Default integrity key for structured saves. - [SyncSimple](/stdlib/ref/file/SyncSimple.html): Generic sync listener for arbitrary types that can be cast to/from int. ## Utilities @@ -170,7 +173,7 @@ If you are choosing a capability, start with the [standard library overview](/st - [Abilities](/stdlib/ref/_wurst/Abilities.html) - [AbilityIds](/stdlib/ref/_wurst/AbilityIds.html) -- [Annotations](/stdlib/ref/_wurst/Annotations.html) +- [Annotations](/stdlib/ref/_wurst/Annotations.html): Marks a documented declaration whose calls are expanded by the compiler. - [Assets](/stdlib/ref/_wurst/Assets.html) - [AttachmentPoints](/stdlib/ref/_wurst/AttachmentPoints.html): Class that contains every known attachmentpoint in game - [Basics](/stdlib/ref/_wurst/Basics.html)