sonolus.py 0.3.2__tar.gz → 0.3.4__tar.gz

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.3.2
+Version: 0.3.4
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/doc_stubs/math.pyi

@@ -154,3 +154,36 @@ def log(x: float, base: float = ...) -> float:
         The logarithm of x to the specified base.
     """
     ...
+
+def sqrt(x: float) -> float:
+    """Compute the square root of x.
+
+    Args:
+        x: A non-negative numeric value.
+
+    Returns:
+        The square root of x.
+    """
+    ...
+
+def degrees(x: float) -> float:
+    """Convert radians to degrees.
+
+    Args:
+        x: An angle in radians.
+
+    Returns:
+        The angle in degrees.
+    """
+    ...
+
+def radians(x: float) -> float:
+    """Convert degrees to radians.
+
+    Args:
+        x: An angle in degrees.
+
+    Returns:
+        The angle in radians.
+    """
+    ...

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/docs/concepts/builtins.md

@@ -2,7 +2,7 @@
 Sonolus.py comes with support for a number of built-in functions.
 
 - `abs(x)`
-- `bool(object)` (for a num argument)
+- `bool(object)`
 - `callable(object)`
 - `enumerate(iterable, start=0)`
 - `filter(function, iterable)`
@@ -38,6 +38,13 @@ Sonolus.py also comes with support for some standard library modules.
 - `ceil(x)`
 - `trunc(x)`
 - `log(x[, base])`
+- `sqrt(x)`
+- `degrees(x)`
+- `radians(x)`
+- `pi`
+- `e`
+- `tau`
+- `inf`
 
 ### random
 - `randrange(stop)`, `random.randrange(start, stop[, step])`

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/docs/concepts/cli.md

@@ -25,4 +25,4 @@ sonolus-py schema
 ## Programmatic usage
 The same functionality can be accessed programmatically as methods of a project.
 
-See [Project][sonolus.script.project.Project] for more information.
+See [Project](../reference/sonolus.script.project.md) for more information.

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/docs/concepts/constructs.md

@@ -1,6 +1,8 @@
 # Constructs
 
-Most standard Python constructs are supported in Sonolus.py.
+Sonolus.py functions as a compiler from Python to Sonolus nodes. While most standard Python constructs are supported,
+there are some limitations compared to standard Python. The following sections outline what Sonolus.py supports and 
+how it differs from standard Python.
 
 ## Key Differences
 

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/docs/concepts/types.md

@@ -11,10 +11,14 @@ the constants `None`, `Ellipsis`, and `NotImplemented`.
 `Num` is the numeric and boolean type in Sonolus.py. It is interchangeable with `int`, `float`, and `bool`.
 Sonolus.py will treat any of these types as `Num`, but it's recommended to use what's appropriate for clarity.
 
+Typically, `Num` isn't directly used in code since `int`, `float`, and `bool` are more specific and easier to read.
+The main exception is for instance checking (`isinstance` or `match` patterns), where `Num` is the only supported
+way to check for numeric or boolean values.
+
 The Sonolus app uses 32-bit floating-point numbers for all numeric values, so precision may be lower compared to Python
-when running on Sonolus.
+when running within Sonolus.
 
-Infinity, NaN, and values outside the range of 32-bit floating-point numbers are not supported.
+NaN and values outside the range of 32-bit floating-point numbers are not supported.
 
 You can import `Num` from `sonolus.script.num`:
 
@@ -42,8 +46,10 @@ Nums support most of the standard Python operations:
     Floating point precision may be lower when running on Sonolus compared to Python.
     Care should be taken when performing precision-sensitive operations.
 
-Nums are the only supported type for boolean operations and control flow conditions.
-As a condition, any nonzero value is considered true, and `0` is considered false.
+As in regular Python, `0` is considered `False`, while any non-zero value is considered `True`.
+
+Objects with an explicit `__bool__` method may also be used in `if`, `while`, `case ... if` expressions as well as with
+the `not` operator. However, the operands of the `and` and `or` operators must be of type `Num`.
 
 - Logical operators: `and`, `or`, `not`
 - Ternary expressions: `... if <condition> else ...`

sonolus_py-0.3.4/docs/index.md

@@ -0,0 +1,27 @@
+# Sonolus.py
+Sonolus.py is a Python library for creating Sonolus engines.
+
+## Installation
+Sonolus.py is available on PyPI and can be installed using a package manager like pip.
+
+=== "pip"
+    ```bash
+    pip install sonolus.py
+    ```
+=== "uv"
+    ```bash
+    uv add sonolus.py
+    ```
+
+## Getting Started
+Example Projects:
+
+- [pydori](https://github.com/qwewqa/pydori): A Bandori-like engine designed to be an example project for Sonolus.py.
+
+New Project Template: [sonolus.py-template-project](https://github.com/qwewqa/sonolus.py-template-project)
+
+## Documentation
+
+- [Overview](overview.md): High-level overview of Sonolus.py.
+- [Concepts](concepts/index.md): Detailed information on concepts and usage.
+- [Reference](reference/index.md): Detailed information on included classes and functions.

sonolus_py-0.3.4/docs/overview.md

@@ -0,0 +1,174 @@
+# Overview
+
+Sonolus.py is a Python library for creating Sonolus engines. This page provides an overview of the key functionality 
+available in the library. For more detailed information, see the [Concepts](concepts/index.md) and 
+[Reference](reference/index.md) sections.
+
+## Features
+Sonolus.py functions by compiling Python code into Sonolus nodes. As such, it supports a subset of Python including
+most syntax and a portion of the standard library. Additionally, Sonolus.py provides its own library of types and
+functions that are specifically designed for use in Sonolus engines.
+
+### Language
+
+#### Syntax
+Most Python syntax is supported, but there are a few limitations:
+
+- Destructuring assignment with the `*` operator is unsupported.
+- Sequence (list and array) `match` patterns with the `*` operator are unsupported.
+- Mapping (dict) `match` patterns are unsupported.
+- Within functions, `import` statements are unsupported.
+- The `global` and `nonlocal` keywords are unsupported.
+- Exception related statements (`try`, `except`, `finally`, `raise`) are unsupported.
+
+#### Compile Time Evaluation
+Sonolus.py will evaluate some expressions at compile time such as basic arithmetic operations on constants,
+boolean logical operations (`and`, `or`, `not`) on constants, and type checks (`isinstance`, `issubclass`).
+
+In control flow constructs like `if` and `match`, Sonolus.py may determine some branches to be unreachable at compile 
+and eliminate them without evaluating them. This allows code like the following to compile successfully:
+
+```python
+a = 1
+if isinstance(a, Vec2):
+    # This branch is eliminated at compile time.
+    # If it were not, compilation would fail because `a` has no attribute `x`.
+    debug_log(a.x)
+else:
+    debug_log(a)
+```
+
+#### Variables
+Numeric (`int`, `float`, `bool`) variables are fully supported and can be freely assigned and modified.
+
+All other variables have the restriction that if the compiler finds multiple possible values for a variable, it may
+not be accessed. For example, the following code will not compile:
+
+```python
+if random() < 0.5:
+    a = Vec2(1, 2)
+else:
+    a = Vec2(3, 4)
+# This will not compile because `a` could have been defined in either branch.
+debug_log(a.x)
+```
+
+#### Function Returns
+Similar to variables, functions returning `int`, `float`, or `bool` can have any number of return statements. Functions
+returning `None` may also have any number of `return` or `return None` statements.
+
+Functions returning any other type must have exactly one `return` statement, and it must be the only exit point of the 
+function. It is ok, however, for a function to have other `return` statements that are eliminated at compile time. 
+For example, the following code will compile successfully:
+
+```python
+def fn(a: int | Vec2):
+    if isinstance(a, Vec2):
+        return a.x + a.y
+    else:
+        return a * 2
+
+fn(123)
+```
+
+### Types
+
+#### Numbers
+Sonolus.py supports `int`, `float`, and `bool` types and most of the standard operations such as mathematical operations
+(`+`, `-`, `*`, `/`, `//`, `%`), comparisons (`<`, `<=`, `>`, `>=`, `==`, `!=`), and boolean operations 
+(`and`, `or`, `not`).
+
+#### Record
+[`Record`](reference/sonolus.script.record.md) is the main way to define custom types in Sonolus.py. It functions similarly to a data class and
+provides a way to define a type with named fields:
+
+```python
+class MyRecord(Record):
+    a: int
+    b: float
+
+my_record = MyRecord(1, b=2.5)
+my_zero_record = +MyRecord  # Short for MyRecord(0, 0.0)
+my_record_copy = +my_record  # Create a copy of my_record with the same values
+my_record.a = 123  # Modify a field of the record
+```
+
+Records may also be generic:
+
+```python
+class MyGenericRecord[T](Record):
+    value: T
+
+my_generic_record = MyGenericRecord[int](42)
+my_generic_record_2 = MyGenericRecord(MyRecord(1, 3.5))  # Type arguments are inferred
+```
+
+#### Array
+[`Array`](reference/sonolus.script.array.md) is a type that represents a fixed-size array of elements of a specific type.
+
+```python
+my_array = Array[int, 3](1, 2, 3)
+my_array_2 = Array(4, 5, 6)  # Type arguments are inferred
+my_zero_array = +Array[int, 3]  # Short for Array[int, 3](0, 0, 0)
+my_array_copy = +my_array  # Create a copy of my_array with the same values
+my_array[2] = 10  # Modify an element of the array
+```
+
+#### Other Types
+Sonolus.py has limited support for other types of values such as strings, tuples, and functions. These have restrictions
+such as not being valid as Record field types or Array element types.
+
+### Modules
+Sonolus.py provides a number of built-in modules that can be used in Sonolus engines. These include:
+
+- Project
+    - [Project](reference/sonolus.script.project.md): Configuration for a Sonolus.py project.
+    - [Engine](reference/sonolus.script.engine.md): Configuration for a Sonolus.py engine.
+    - [Level](reference/sonolus.script.level.md): Configuration for a Sonolus.py level.
+    - [Archetype](reference/sonolus.script.archetype.md): Engine archetypes and their configuration.
+- Core Types
+    - [Array](reference/sonolus.script.array.md): Fixed-size arrays.
+    - [Num](reference/sonolus.script.num.md): Numeric values (int, float, bool).
+    - [Record](reference/sonolus.script.record.md): User-defined types with named fields.
+- Engine Resources
+    - [Bucket](reference/sonolus.script.bucket.md): Judgment buckets.
+    - [Effect](reference/sonolus.script.effect.md): Sound effects.
+    - [Instruction](reference/sonolus.script.instruction.md): Tutorial instructions.
+    - [Options](reference/sonolus.script.options.md): Engine options.
+    - [Particle](reference/sonolus.script.particle.md): Particle effects.
+    - [Sprite](reference/sonolus.script.sprite.md): Sprites and skins.
+    - [UI](reference/sonolus.script.ui.md): Engine ui configuration.
+- Sonolus Runtime
+    - [Globals](reference/sonolus.script.globals.md): Level data and level memory definition.
+    - [Runtime](reference/sonolus.script.runtime.md): Runtime functions like time and ui configuration.
+    - [Stream](reference/sonolus.script.stream.md): Data streams recorded in play mode and used in watch mode.
+    - [Text](reference/sonolus.script.text.md): Standard Sonolus text constants.
+    - [Timing](reference/sonolus.script.timing.md): Beat and timescale related functions.
+- Python Builtins
+    - [builtins](reference/builtins.md): Supported Python builtins.
+    - [math](reference/math.md): Supported math functions.
+    - [random](reference/random.md): Supported random functions.
+- Utilities
+    - [ArrayLike](reference/sonolus.script.array_like.md): Mixin for array functionality.
+    - [Containers](reference/sonolus.script.containers.md): Additional container types like `VarArray` and `ArrayMap`.
+    - [Debug](reference/sonolus.script.debug.md): Debugging utilities.
+    - [Easing](reference/sonolus.script.easing.md): Easing functions for animations.
+    - [Interval](reference/sonolus.script.interval.md): Mathematical intervals.
+    - [Iterator](reference/sonolus.script.iterator.md): Iterators over collections.
+    - [Printing](reference/sonolus.script.printing.md): Preview mode number printing.
+    - [Quad](reference/sonolus.script.quad.md): Quadrilaterals.
+    - [Transform](reference/sonolus.script.transform.md): Transformations like translation, rotation, and scaling.
+    - [Values](reference/sonolus.script.values.md): Generic utilities for working with values.
+    - [Vec](reference/sonolus.script.vec.md): The Vec2 type and related functions.
+
+For more details, see the [Reference](reference/index.md) section.
+
+## Getting Started
+
+Before making a new Sonolus.py engine, it may be helpful to look at some existing projects to see how they use
+the library:
+
+- [pydori](https://github.com/qwewqa/pydori): A Bandori-like engine designed to be an example project for Sonolus.py.
+
+If you're starting a new project, you'll probably want to use the
+[new project template](https://github.com/qwewqa/sonolus.py-template-project).

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/mkdocs.yml

@@ -70,6 +70,7 @@ markdown_extensions:
       alternate_style: true
 nav:
   - index.md
+  - Overview: overview.md
   - Concepts:
       - concepts/index.md
       - concepts/types.md

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sonolus.py"
-version = "0.3.2"
+version = "0.3.4"
 description = "Sonolus engine development in Python"
 readme = "README.md"
 requires-python = ">=3.12"

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/sonolus/backend/finalize.py

@@ -1,3 +1,5 @@
+from math import isfinite, isinf, isnan
+
 from sonolus.backend.ir import IRConst, IRGet, IRInstr, IRPureInstr, IRSet
 from sonolus.backend.node import ConstantNode, EngineNode, FunctionNode
 from sonolus.backend.ops import Op
@@ -54,10 +56,20 @@ def cfg_to_engine_node(entry: BasicBlock):
 
 def ir_to_engine_node(stmt) -> EngineNode:
     match stmt:
-        case int() | float():
-            return ConstantNode(value=float(stmt))
-        case IRConst(value=int(value) | float(value)):
-            return ConstantNode(value=value)
+        case int(value) | float(value) | IRConst(value=int(value) | float(value)):
+            value = float(value)
+            if value.is_integer():
+                return ConstantNode(value=int(value))
+            elif isfinite(value):
+                return ConstantNode(value=value)
+            elif isinf(value):
+                # Read values from ROM
+                return FunctionNode(Op.Get, args=[ConstantNode(value=3000), ConstantNode(value=1 if value > 0 else 2)])
+            elif isnan(value):
+                # Read value from ROM
+                return FunctionNode(Op.Get, args=[ConstantNode(value=3000), ConstantNode(value=0)])
+            else:
+                raise ValueError(f"Invalid constant value: {value}")
         case IRPureInstr(op=op, args=args) | IRInstr(op=op, args=args):
             return FunctionNode(func=op, args=[ir_to_engine_node(arg) for arg in args])
         case IRGet(place=place):

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/sonolus/backend/visitor.py

@@ -359,7 +359,7 @@ class Visitor(ast.NodeVisitor):
         self.loop_head_ctxs.append(header_ctx)
         self.break_ctxs.append([])
         set_ctx(header_ctx)
-        has_next = self.ensure_boolean_num(self.handle_call(node, iterator.has_next))
+        has_next = self.convert_to_boolean_num(node, self.handle_call(node, iterator.has_next))
         if has_next._is_py_() and not has_next._as_py_():
             # The loop will never run, continue after evaluating the condition
             self.loop_head_ctxs.pop()
@@ -400,7 +400,7 @@ class Visitor(ast.NodeVisitor):
         self.loop_head_ctxs.append(header_ctx)
         self.break_ctxs.append([])
         set_ctx(header_ctx)
-        test = self.ensure_boolean_num(self.visit(node.test))
+        test = self.convert_to_boolean_num(node.test, self.visit(node.test))
         if test._is_py_():
             if test._as_py_():
                 # The loop will run until a break / return
@@ -454,7 +454,7 @@ class Visitor(ast.NodeVisitor):
         set_ctx(after_ctx)
 
     def visit_If(self, node):
-        test = self.ensure_boolean_num(self.visit(node.test))
+        test = self.convert_to_boolean_num(node.test, self.visit(node.test))
 
         if test._is_py_():
             if test._as_py_():
@@ -507,7 +507,9 @@ class Visitor(ast.NodeVisitor):
                 set_ctx(false_ctx)
                 continue
             set_ctx(true_ctx)
-            guard = self.ensure_boolean_num(self.visit(case.guard)) if case.guard else validate_value(True)
+            guard = (
+                self.convert_to_boolean_num(case.guard, self.visit(case.guard)) if case.guard else validate_value(True)
+            )
             if guard._is_py_():
                 if guard._as_py_():
                     for stmt in case.body:
@@ -544,7 +546,7 @@ class Visitor(ast.NodeVisitor):
         match pattern:
             case ast.MatchValue(value=value):
                 value = self.visit(value)
-                test = self.ensure_boolean_num(validate_value(subject == value))
+                test = self.convert_to_boolean_num(pattern, validate_value(subject == value))
                 if test._is_py_():
                     if test._as_py_():
                         return ctx(), ctx().into_dead()
@@ -574,7 +576,7 @@ class Visitor(ast.NodeVisitor):
                 target_len = len(patterns)
                 if not (isinstance(subject, Sequence | TupleImpl)):
                     return ctx().into_dead(), ctx()
-                length_test = self.ensure_boolean_num(validate_value(_len(subject) == target_len))
+                length_test = self.convert_to_boolean_num(pattern, validate_value(_len(subject) == target_len))
                 ctx_init = ctx()
                 if not length_test._is_py_():
                     ctx_init.test = length_test.ir()
@@ -739,7 +741,7 @@ class Visitor(ast.NodeVisitor):
     def visit_UnaryOp(self, node):
         operand = self.visit(node.operand)
         if isinstance(node.op, ast.Not):
-            return self.ensure_boolean_num(operand).not_()
+            return self.convert_to_boolean_num(node, operand).not_()
         op = unary_ops[type(node.op)]
         if operand._is_py_():
             operand_py = operand._as_py_()
@@ -768,7 +770,7 @@ class Visitor(ast.NodeVisitor):
         return validate_value(fn)
 
     def visit_IfExp(self, node):
-        test = self.ensure_boolean_num(self.visit(node.test))
+        test = self.convert_to_boolean_num(node.test, self.visit(node.test))
 
         if test._is_py_():
             if test._as_py_():
@@ -1076,7 +1078,7 @@ class Visitor(ast.NodeVisitor):
 
     def handle_call[**P, R](
         self, node: ast.stmt | ast.expr, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
-    ) -> R:
+    ) -> R | Value:
         """Handles a call to the given callable."""
         self.active_ctx = ctx()
         if (
@@ -1127,6 +1129,20 @@ class Visitor(ast.NodeVisitor):
             raise TypeError(f"Invalid type where a bool (Num) was expected: {type(value).__name__}")
         return value
 
+    def convert_to_boolean_num(self, node, value: Value) -> Num:
+        if _is_num(value):
+            return value
+        if hasattr(type(value), "__bool__"):
+            return self.ensure_boolean_num(self.handle_call(node, type(value).__bool__, validate_value(value)))
+        if hasattr(type(value), "__len__"):
+            length = self.handle_call(node, type(value).__len__, validate_value(value))
+            if not _is_num(length):
+                raise TypeError(f"Invalid type for __len__: {type(length).__name__}")
+            if length._is_py_():
+                return Num._accept_(length._as_py_() > 0)
+            return length > Num._accept_(0)
+        raise TypeError(f"Converting {type(value).__name__} to bool is not supported")
+
     def arguments_to_signature(self, arguments: ast.arguments) -> inspect.Signature:
         parameters: list[inspect.Parameter] = []
         pos_only_count = len(arguments.posonlyargs)

{sonolus_py-0.3.2 → sonolus_py-0.3.4}/sonolus/script/archetype.py

@@ -312,7 +312,7 @@ class StandardImport:
 def callback[T: Callable](*, order: int = 0) -> Callable[[T], T]:
     """Annotate a callback with its order.
 
-    Callbacks are execute from lowest to highest order. By default, callbacks have an order of 0.
+    Callbacks are executed from lowest to highest order. By default, callbacks have an order of 0.
 
     Usage:
         ```python
@@ -338,9 +338,9 @@ class _ArchetypeSelfData:
 
 
 class _ArchetypeReferenceData:
-    index: Num
+    index: int
 
-    def __init__(self, index: Num):
+    def __init__(self, index: int):
         self.index = index
 
 
@@ -416,21 +416,21 @@ class _BaseArchetype:
 
     @classmethod
     @meta_fn
-    def at(cls, index: Num) -> Self:
+    def at(cls, index: int) -> Self:
         result = cls._new()
         result._data_ = _ArchetypeReferenceData(index=Num._accept_(index))
         return result
 
     @classmethod
     @meta_fn
-    def is_at(cls, index: Num) -> bool:
+    def is_at(cls, index: int) -> bool:
         if not ctx():
             raise RuntimeError("is_at is only available during compilation")
         return entity_info_at(index).archetype_id == cls.id()
 
     @classmethod
     @meta_fn
-    def id(cls):
+    def id(cls) -> int:
         if not ctx():
             raise RuntimeError("Archetype id is only available during compilation")
         result = ctx().global_state.archetypes.get(cls)
@@ -549,11 +549,19 @@ class _BaseArchetype:
                     metadata = _annotation_defaults.get(metadata, metadata)
                 if isinstance(metadata, _ArchetypeFieldInfo):
                     if field_info is not None:
-                        raise TypeError(
-                            f"Unexpected multiple field annotations for '{name}', "
-                            f"expected exactly one of imported, exported, entity_memory, or shared_memory"
-                        )
-                    field_info = metadata
+                        if field_info.storage == metadata.storage and field_info.name is None:
+                            field_info = metadata
+                        elif field_info.storage == metadata.storage and (
+                            metadata.name is None or field_info.name == metadata.name
+                        ):
+                            pass
+                        else:
+                            raise TypeError(
+                                f"Unexpected multiple field annotations for '{name}', "
+                                f"expected exactly one of imported, exported, entity_memory, or shared_memory"
+                            )
+                    else:
+                        field_info = metadata
             if field_info is None:
                 raise TypeError(
                     f"Missing field annotation for '{name}', "
@@ -880,7 +888,7 @@ class WatchArchetype(_BaseArchetype):
             case _ArchetypeSelfData():
                 return _deref(ctx().blocks.EntityInfo, 0, WatchEntityInfo)
             case _ArchetypeReferenceData(index=index):
-                return _deref(ctx().blocks.EntityInfoArray, index * WatchEntityInfo._size_(), PlayEntityInfo)
+                return _deref(ctx().blocks.EntityInfoArray, index * WatchEntityInfo._size_(), WatchEntityInfo)
             case _:
                 raise RuntimeError("Info is only accessible from the entity itself")
 
@@ -984,7 +992,7 @@ class PreviewArchetype(_BaseArchetype):
 
 
 @meta_fn
-def entity_info_at(index: Num) -> PlayEntityInfo | WatchEntityInfo | PreviewEntityInfo:
+def entity_info_at(index: int) -> PlayEntityInfo | WatchEntityInfo | PreviewEntityInfo:
     """Retrieve entity info of the entity at the given index.
 
     Available in play, watch, and preview mode.
@@ -1039,24 +1047,24 @@ class PreviewEntityInfo(Record):
 class ArchetypeLife(Record):
     """How an entity contributes to life."""
 
-    perfect_increment: Num
+    perfect_increment: int
     """Life increment for a perfect judgment."""
 
-    great_increment: Num
+    great_increment: int
     """Life increment for a great judgment."""
 
-    good_increment: Num
+    good_increment: int
     """Life increment for a good judgment."""
 
-    miss_increment: Num
+    miss_increment: int
     """Life increment for a miss judgment."""
 
     def update(
         self,
-        perfect_increment: Num | None = None,
-        great_increment: Num | None = None,
-        good_increment: Num | None = None,
-        miss_increment: Num | None = None,
+        perfect_increment: int | None = None,
+        great_increment: int | None = None,
+        good_increment: int | None = None,
+        miss_increment: int | None = None,
     ):
         """Update the life increments."""
         if perfect_increment is not None:
@@ -1106,10 +1114,20 @@ class EntityRef[A: _BaseArchetype](Record):
         """Return a new reference with the given archetype type."""
         return EntityRef[archetype](index=self.index)
 
+    @meta_fn
     def get(self) -> A:
         """Get the entity."""
+        if ref := getattr(self, "_ref_", None):
+            return ref
         return self.archetype().at(self.index)
 
+    @meta_fn
+    def get_as(self, archetype: type[_BaseArchetype]) -> _BaseArchetype:
+        """Get the entity as the given archetype type."""
+        if getattr(archetype, "_ref_", None):
+            raise TypeError("Using get_as in level data is not supported.")
+        return self.with_archetype(archetype).get()
+
     def archetype_matches(self) -> bool:
         """Check if entity at the index is precisely of the archetype."""
         return self.index >= 0 and self.archetype().is_at(self.index)
@@ -1117,7 +1135,7 @@ class EntityRef[A: _BaseArchetype](Record):
     def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue | str]:
         ref = getattr(self, "_ref_", None)
         if ref is None:
-            return [self.index]
+            return Num._accept_(self.index)._to_list_()
         else:
             if ref not in level_refs:
                 raise KeyError("Reference to entity not in level data")