Merge dev to main for v0.5.7

.editorconfig

@@ -0,0 +1,25 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+max_line_length = 100
+
+[*.{nut,tcl}]
+max_line_length = 100
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+max_line_length = 81
+trim_trailing_whitespace = false
+
+[*.{cfg,ini,flake8}]
+indent_size = 4

.flake8

@@ -1,4 +1,5 @@
 [flake8]
 ignore = E501, W503
 exclude =
-    .venv
+    .venv
+    .env

.gitattributes

@@ -1,3 +1,12 @@
 * text=auto eol=lf
 
 *.absp text linguist-language=JSON linguist-detectable=true diff=json
+
+.github                 export-ignore
+.vscode                 export-ignore
+.editorconfig           export-ignore
+.flake8                 export-ignore
+.gitattributes          export-ignore
+.gitignore              export-ignore
+.markdownlint-cli2.yaml export-ignore
+AGENTS.md               export-ignore

.gitignore

@@ -190,7 +190,9 @@ cython_debug/
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
 #  and can be added to the global gitignore or merged into this file. However, if you prefer, 
 #  you could uncomment the following to ignore the entire vscode folder
-.vscode/
+#  (shared workspace config is un-ignored below)
+.vscode/*
+!.vscode/extensions.json
 
 # Ruff stuff:
 .ruff_cache/
@@ -213,7 +215,5 @@ __marimo__/
 # Agents
 .agents/
 
-### ABS Specific ###
-
-# ABS cache files
-abs_cache/
+# Compiled engine C
+engine/c/build/

.markdownlint-cli2.yaml

@@ -1,2 +1,9 @@
 ignores:
   - "LICENSE"
+  - ".venv/**"
+
+globs:
+  - "**/*.{md,markdown}"
+
+config:
+  MD013: false

.vscode/extensions.json

@@ -0,0 +1,17 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+
+    "charliermarsh.ruff",
+    "astral-sh.ty",
+    "ms-python.mypy-type-checker",
+    "ms-python.flake8",
+    "nwgh.bandit",
+    "kennethlove.interrogate",
+    "DavidAnson.vscode-markdownlint",
+
+    "marcinbar.vscode-squirrel",
+    "rashwell.tcl"
+  ]
+}

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Contributions of all types are welcome, including:
 
 Please read this document before submitting changes.
 
-> [!Note]
+> [!NOTE]
 > All contributions should target the `dev` branch. Changes are reviewed and
 > tested there before being merged into `main` for releases.
 
@@ -98,6 +98,7 @@ All contributions should prioritize:
   provided they do not produce large or significant changes.
 - **Trivial Edits Allowed:** Very small, obvious changes such as typo fixes,
   whitespace cleanup, or minor wording updates are permitted.
+- **Commit messages allowed**: Generated commit messages are allowed as long as they are an accurate description of the change being made.
 - **Human Responsibility:** All contributions must be reviewed, tested, and
   approved by a human author.
 
@@ -115,7 +116,7 @@ All contributions should prioritize:
 - **Trivial Changes Only:** Very small edits are allowed.
 
 <!-- markdownlint-disable MD033 -->
-<small>This AI Policy is derived from [Gravel's AI Policy](https://github.com/Pacsfury/Gravel-Launcher/blob/main/AI-POLICY.md).</small>
+<small>This AI Policy is derived from [Gravel's AI Policy](https://github.com/Pacsfury/Gravel-Launcher/blob/ed0301ba7aa82342ac937cf1d149d68d00008724/AI-POLICY.md).</small>
 <!-- markdownlint-enable MD033 -->
 
 ---

MANIFEST.in

@@ -1,3 +1,4 @@
 include engine/py.typed
 recursive-include engine/tcl *.tcl
 recursive-include engine/nut *.nut
+recursive-include engine/c *.c *.h

docs/README.md

@@ -3,3 +3,9 @@
 This folder contains the documentation for ABS Engine.
 
 Documentation may include guides, tutorials, references, examples, and other resources related to using and developing games with ABS Engine.
+
+> [!TIP]
+> If you're new to ABS Engine, check out:
+>
+> * [Scripting Docs](scripting.md)
+> * [Build Tools Docs](using_build_tools.md)

docs/accessing_the_console.md

@@ -14,13 +14,13 @@ python3 run.pyw
 
 Make sure you run it with the `python3` or `py` command. Directly using the file path will not show the console.
 
-Bad Example:
+Don't do this:
 
 ```powershell
 & "C:/Users/User/ABS-Engine/run.pyw"
 ```
 
-*Good* Example:
+Do this:
 
 ```powershell
 py C:/Users/User/ABS-Engine/run.pyw

docs/debugging_games.md

@@ -54,13 +54,13 @@ Here are the main parts of the message:
 ```
 
 **Type**: The severity of the message (can be "INFO", "WARNING", or "CRITICAL")
-**Source**: Shows which module the message originated from. In this example, the message came from `engine/core.py`.
+**Source**: Shows which module the message originated from. In this example, the message came from `engine/core/__init__.py`.
 **Message**: The message being printed
 
 Example of a critical error message:
 
 ```text
-(CRITICAL) ENGINE.GUI: Initialized game
+(CRITICAL) ENGINE.GUI: Could not load icon image.
    |              |           |
    |              |______     |_______
    |              |Source|    |Message|

docs/errors.md

@@ -4,8 +4,7 @@ This document describes ABS Engine's error module (`engine.core.errors`).
 
 ## Overview
 
-`engine.core.errors` is not only for fatal, unrecoverable errors. It also will
-define precise, engine-specific exception types for situations that
+`engine.core.errors` is not only for fatal, unrecoverable errors. It will also define precise, engine-specific exception types for situations that
 could otherwise be mistaken for an ordinary, expected error (e.g. a
 generic `ValueError` or `KeyError`) but that the user of the engine
 should actually be catching and handling deliberately. Naming these
@@ -41,7 +40,7 @@ def __init__(self, message: str) -> Never: ...
 from engine.core.errors import ABSFatalError
 
 if renderer_context_lost:
-    ABSFatalError("Lost graphics context, cannot continue")
+    raise ABSFatalError("Lost graphics context, cannot continue")
 ```
 
 Do **not** wrap this in a `try`/`except` expecting to recover. It's

docs/game_file_structure.md

@@ -18,7 +18,7 @@ MyGame
 ```
 
 Do not create game.absp, as it is generated by ABS Engine.
-It contains the project name, game settings, and entity names,
+It contains the project name, game settings, entity names,
 properties, and data.
 
 ## Game Data Structure

docs/music.md

@@ -0,0 +1,78 @@
+# Music
+
+Every [`Game`](using_the_engine_api.md) owns a small music mixer as
+`game.music`. It plays one background track at a time, which is what
+background music usually is: a single looping track that changes when the
+scene or the mood does.
+
+From a [script](scripting.md), reach it through the entity's scene:
+
+```python
+def init(entity):
+    game = entity.parent.game
+    game.music.play("assets/theme.ogg")
+```
+
+> [!TIP]
+> Music is not entity-specific, so start it from your main script.
+> See the tip about main scripts in the [Main Scripts section of the scripting docs](scripting.md#main-scripts).
+
+Using the engine API directly:
+
+```python
+from engine.core import Game
+
+
+game = Game(GP_BASE_PATH=".")
+
+game.music.set_volume(0.5)
+game.music.play("data/audio/theme.ogg")
+
+game.run()
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `play(track, *, loops=-1, fade_ms=0)` | Start `track`, replacing whatever was playing. `track` is a path relative to the project root. `loops` is how many extra times to repeat it, `-1` forever. `fade_ms` fades the track in. |
+| `stop(*, fade_ms=0)` | Stop the current track and forget it. `fade_ms` fades it out instead of cutting it. |
+| `pause()` | Hold the current track where it is. |
+| `resume()` | Carry on with a paused track. |
+| `set_volume(volume)` | Set how loud music plays, from `0.0` to `1.0`. Values outside that range are clamped. Applies to later tracks too. |
+| `get_volume()` | Return the volume music is set to play at, from `0.0` to `1.0`. |
+| `is_playing()` | Return whether a track is audible right now. A paused track is not playing. |
+
+## Properties
+
+| Property | Description | Type |
+| --- | --- | --- |
+| `track` | Path of the loaded track, or `None` when nothing is loaded | `Optional[str]` |
+| `available` | Whether an audio device was opened | `bool` |
+| `base_path` | Project root that `track` paths are given relative to | `str` |
+
+## Formats
+
+Playable formats come from pygame, which uses SDL_mixer. OGG and WAV are the
+safe choices; MP3 support depends on how the player's SDL_mixer was built.
+Prefer OGG for music, since it is compressed and always supported.
+
+## Machines Without Audio
+
+Some machines have no working audio device: a headless build server, a
+container, or a desktop with sound disabled. Rather than crash a game over
+it, the mixer logs a warning at startup and sets `available` to `False`.
+Every method stays safe to call, and none of them do anything:
+
+```python
+def init(entity):
+    music = entity.parent.game.music
+
+    music.play("data/audio/theme.ogg")  # Fine. Silent, but fine.
+
+    if not music.available:
+        entity.parent.game.gamedata["subtitles"] = True
+```
+
+A missing or unreadable track file is handled the same way: the load is
+logged as a warning and whatever was already playing keeps playing.

docs/scenes.md

@@ -12,6 +12,7 @@ Scenes are managed by `engine.core.Game`, and each scene is represented by
 Every `Game` has:
 
 - `game.scenes`: A list of all scenes in the game.
+- `game.music`: See [this article](music.md)
 - `game.current_scene`: The index of the scene currently being shown.
 - `game.add_scene()`: A method that creates a new scene and returns its index.
 - `game.switch_scene(scene_index)`: A method that changes the active scene.

docs/scripting.md

@@ -5,6 +5,12 @@ With scripting, you can move and manipulate objects, create animations, and much
 In other words, scripting allows you to make entities in your game _do things_.
 Here's how to get started:
 
+> [!TIP]
+> If you're planning on using the engine API, see:
+>
+> * [Using the Engine API Directly](using_the_engine_api.md)
+> * [OSE Docs](ose.md)
+
 To create a script file, first follow the
 [recommended file structure](game_file_structure.md).
 The `assets/` folder is not needed for this tutorial.
@@ -23,7 +29,7 @@ Then, launch ABS Engine and follow these steps:
 6. Click "Save", then "Save Project"
 7. Verify that `game.absp` was saved in your project folder
 
->[!Tip]
+> [!TIP]
 > Name your scripts after the entity they're attached to.
 > This makes it easy to identify them later.
 
@@ -41,18 +47,6 @@ def update(entity, dt):
 Go back to ABS Engine and click "Run".
 You should see a white square moving continuously from left to right.
 
->[!Tip]
-> Because the engine requires a script to
-> be attached to an entity in your game,
-> put everything in the game that is not
-> entity-specific (e.g. playing background
-> music, etc.) in the script attached to
-> the player entity (The entity that the
-> player controls). This is called a main
-> script. If your game does not have a player
-> entity, place a new entity off screen that
-> has the main script attached to it.
-
 Let's break down what this code does.
 In a script file, three functions are commonly defined:
 
@@ -63,7 +57,9 @@ event(entity: Entity, event: pygame.event.Event) -> None
 ```
 
 `init()`   - Called once when the game starts
+
 `update()` - Called every frame (multiple times per second)
+
 `event()`  - Called when a pygame event is triggered
 
 ## Entity Properties
@@ -82,7 +78,7 @@ The `engine.core.Entity` class has the following properties:
 | `width` | Width in pixels | `float` |
 | `height` | Height in pixels | `float` |
 | `color` | RGB color value | `tuple[int, int, int]` |
-| `rect` | Pygame rect object on screen | `pygame.Rect` |
+| `rect` | Pygame rect object on screen | `pygame.FRect` |
 | `scriptfile` | Path to the attached script | `str` |
 | `image` | Image attached to entity | `EntityImage` or `None` |
 | `id` | Unique entity UUID | `str` |
@@ -94,9 +90,9 @@ The `engine.core.Entity` class has the following properties:
 
 The `init()`, `update()`, and `event()` functions are callback functions that ABS Engine calls at specific times:
 
-- `init(entity: Entity) -> None`                              - Called when the game starts
-- `update(entity: Entity, dt: float) -> None`                 - Called every frame
-- `event(entity: Entity, event: pygame.event.Event) -> None`  - Called when an a pygame event occurs
+* `init(entity: Entity) -> None`                              - Called when the game starts
+* `update(entity: Entity, dt: float) -> None`                 - Called every frame
+* `event(entity: Entity, event: pygame.event.Event) -> None`  - Called when an a pygame event occurs
 
 Here's an example script that creates a simple game with player movement.
 The game uses a top-down perspective with a player-controlled square
@@ -151,3 +147,17 @@ def event(entity, event):
 > If the game window freezes or shows a black screen at startup,
 > check that your script file has no syntax errors. It is completely normal for a game to crash if there are code errors.
 > See [Debugging Games](debugging_games.md) for help diagnosing issues.
+
+## Main Scripts
+
+> [!TIP]
+> Because the engine requires a script to
+> be attached to an entity in your game,
+> put everything in the game that is not
+> entity-specific (e.g. playing background
+> music, etc.) in the script attached to
+> the player entity (The entity that the
+> player controls). This is called a main
+> script. If your game does not have a player
+> entity, place a new entity off screen that
+> has the main script attached to it.

docs/using_build_tools.md

@@ -9,7 +9,7 @@ Click "Build Game", then "Yes".
 ABS Engine will now compile the game and all of its dependencies
 to the folder that contains the project file, using Pyinstaller
 under the hood. A "Building Game" window stays open with a progress
-bar while this happens, and only closes once Pyinstaller has
+bar and log while this happens, and only closes once Pyinstaller has
 actually finished.
 
 When you run the new `run.py` file in that folder,