loreline 0.9.1 → 0.10.0

package/README.md

@@ -8,7 +8,7 @@ Loreline works everywhere: game engines, web apps, or standalone projects. It ad
 
 ### Get started
 
-The documentation and an interactive playground are available on **[loreline.app](https://loreline.app)**.
+The documentation, an interactive playground and a downloadable editor (Loreline Writer) are available on **[loreline.app](https://loreline.app)**.
 
 ## Building Loreline
 
@@ -29,12 +29,15 @@ npm install    # Install Node.js dependencies (esbuild, tsx, etc.)
 node ./setup --js          # Build JavaScript library (js/loreline.js)
 node ./setup --cs          # Export C# source files (cs/Loreline/)
 node ./setup --cs --cs-dll # Export C# + build Loreline.dll
-node ./setup --cs-generics # Export C# test runner without erase-generics (see CS_COMPATIBILITY.md)
+node ./setup --cs-generics # Export C# test runner without erase-generics
 node ./setup --py          # Build Python package (py/loreline/)
 node ./setup --lua         # Build Lua module (lua/loreline/)
+node ./setup --php         # Build PHP package (php/)
+node ./setup --php-cli     # Build PHP CLI (build/php-cli/)
 node ./setup --cpp         # Build native CLI (loreline / loreline.exe)
 node ./setup --cpp-lib     # Build C++ shared library
 node ./setup --jvm         # Build JVM jar (jvm/loreline.jar)
+node ./setup --gdscript    # Export pure-GDScript Godot addon (godot/gdscript/)
 ```
 
 ### Setting up samples
@@ -55,17 +58,28 @@ For loreline-lua, run `--lua` first.
 
 ### Testing
 
-Python, Lua, JS, and JVM tests require running the corresponding build step first (e.g. `node ./setup --py` before Python tests).
+Python, Lua, PHP, JS, JVM and GDScript tests require running the corresponding build step first (e.g. `node ./setup --py` before Python tests). GDScript tests also need a Godot 4 binary on the PATH (or pointed to by the `GODOT_BIN` environment variable).
 
 ```sh
 node run test ./test                    # Run Neko tests only
 python3 py/test-runner.py ./test        # Run Python tests only
 lua5.4 lua/test-runner.lua ./test       # Run Lua tests only
+php php/test-runner.php ./test          # Run PHP tests only
+php build/php-cli/index.php test ./test # Run PHP CLI tests only
 npx tsx js/test-runner.ts ./test        # Run JS tests only
 java -cp jvm/loreline.jar:build/jvm/test TestRunner ./test  # Run JVM tests only
-node ./setup --test                     # Build and run all test suites (Neko + C# + C# AOT + C# (with generics) + JS + C++ lib + Python + Lua + JVM)
+node ./setup --gdscript-test            # Run GDScript tests only (headless Godot)
+node ./setup --test                     # Build and run all test suites (Neko + C# + C# AOT + C# (with generics) + JS + C++ lib + Python + Lua + PHP + PHP CLI + JVM)
 ```
 
+### How Loreline is authored
+
+Loreline's runtime is essentially handwritten, so the code you embed when depending on it can be considered almost entirely free of AI-generated code.
+
+That said, I used coding assistants for peripheral work: unit-tests, scaffolding, debugging, documenting the code, continuous integration, and help in making surgical changes to the runtime. These improve the overall reliability and quality of Loreline, make sure that anything tested won't break in the future, and give me more bandwidth for the more creative, interesting and trickier parts of Loreline itself. I weighed that this targeted use would benefit the users of the project, and I take entire responsibility for all the code and design choices in this repository.
+
+For some context on where I stand, I don't endorse the use of generative AI as a general rule: I do care a lot about writing code myself and human authorship in general, and I also don't use any AI-generated assets or content for the games I make.
+
 ## License
 
 MIT License

package/js/loreline.d.ts

@@ -275,7 +275,7 @@ export class Loreline {
      *
      * For each file involved in the script (root + transitively imported), the
      * corresponding translation file is looked up by inserting `.<locale>` before
-     * the extension (e.g. `characters.lor` → `characters.fr.lor`). Missing translation
+     * the extension (e.g. `characters.lor` -> `characters.fr.lor`). Missing translation
      * files are silently skipped. The returned map can be passed as
      * `InterpreterOptions.translations` to `play()` or `resume()`.
      *
@@ -302,9 +302,9 @@ export class Loreline {
      *
      * By default only `.<locale>.lor` files are tried by `loadLocale`. Call
      * this to opt in to additional formats:
-     * - `"po"`    — GNU gettext PO (`.po`)
-     * - `"xliff"` — XLIFF 1.2 / 2.x (`.xliff`, `.xlf`)
-     * - `"csv"`   — CSV / TSV (`.csv`, `.tsv`)
+     * - `"po"`:    GNU gettext PO (`.po`)
+     * - `"xliff"`: XLIFF 1.2 / 2.x (`.xliff`, `.xlf`)
+     * - `"csv"`:   CSV / TSV (`.csv`, `.tsv`)
      *
      * Unknown names are accepted silently (forward-compat for future formats).
      *
@@ -322,7 +322,7 @@ export class Loreline {
      * call throws, and this is set to the same error so it can be inspected
      * after the catch.
      *
-     * Not thread-safe — read immediately after the call returns.
+     * Not thread-safe: read immediately after the call returns.
      */
     static lastError(): Error | null;
 
@@ -399,6 +399,10 @@ export class Interpreter {
     /**
      * Gets a specific field of a character.
      *
+     * Container values (key-value objects and arrays) are plain JS objects
+     * and arrays: field accessors and custom functions exchange idiomatic
+     * JS values in both directions.
+     *
      * @param character The name of the character
      * @param name The name of the field to get
      * @return The field value or null if the character or field doesn't exist