sonolus.py 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

sonolus/script/globals.py

@@ -8,7 +8,7 @@ from sonolus.script.internal.generic import validate_concrete_type
 from sonolus.script.internal.value import Value
 
 
-class GlobalInfo:
+class _GlobalInfo:
     def __init__(self, name: str, size: int, blocks: dict[Mode, Block], offset: int | None):
         self.name = name
         self.size = size
@@ -16,7 +16,7 @@ class GlobalInfo:
         self.offset = offset
 
 
-class GlobalField(SonolusDescriptor):
+class _GlobalField(SonolusDescriptor):
     def __init__(self, name: str, type_: type[Value], index: int, offset: int):
         self.name = name
         self.type = type_
@@ -49,7 +49,7 @@ class GlobalField(SonolusDescriptor):
             target._copy_from_(value)
 
 
-class GlobalPlaceholder:
+class _GlobalPlaceholder:
     def __init__(self, type_: type[Value], blocks: dict[Mode, Block], offset: int | None):
         self.type = type_
         self.blocks = blocks
@@ -65,10 +65,10 @@ class GlobalPlaceholder:
         return self.type._from_place_(base)
 
 
-def create_global(cls: type, blocks: dict[Mode, Block], offset: int | None):
+def _create_global(cls: type, blocks: dict[Mode, Block], offset: int | None):
     if issubclass(cls, Value):
         cls = validate_concrete_type(cls)
-        return GlobalPlaceholder(cls, blocks, offset)
+        return _GlobalPlaceholder(cls, blocks, offset)
     if len(cls.__bases__) != 1:
         raise TypeError("Expected a class with no bases or a Value subclass")
     field_offset = 0
@@ -77,61 +77,61 @@ def create_global(cls: type, blocks: dict[Mode, Block], offset: int | None):
         annotation,
     ) in enumerate(inspect.get_annotations(cls, eval_str=True).items()):
         type_ = validate_concrete_type(annotation)
-        setattr(cls, name, GlobalField(name, type_, i, field_offset))
+        setattr(cls, name, _GlobalField(name, type_, i, field_offset))
         field_offset += type_._size_()
-    cls._global_info_ = GlobalInfo(cls.__name__, field_offset, blocks, offset)
+    cls._global_info_ = _GlobalInfo(cls.__name__, field_offset, blocks, offset)
     cls._is_comptime_value_ = True
     return cls()
 
 
 @dataclass_transform()
 def _play_runtime_environment[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PLAY: PlayBlock.RuntimeEnvironment}, 0)
+    return _create_global(cls, {Mode.PLAY: PlayBlock.RuntimeEnvironment}, 0)
 
 
 @dataclass_transform()
 def _watch_runtime_environment[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.WATCH: WatchBlock.RuntimeEnvironment}, 0)
+    return _create_global(cls, {Mode.WATCH: WatchBlock.RuntimeEnvironment}, 0)
 
 
 @dataclass_transform()
 def _tutorial_runtime_environment[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeEnvironment}, 0)
+    return _create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeEnvironment}, 0)
 
 
 @dataclass_transform()
 def _preview_runtime_environment[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeEnvironment}, 0)
+    return _create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeEnvironment}, 0)
 
 
 @dataclass_transform()
 def _play_runtime_update[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PLAY: PlayBlock.RuntimeUpdate}, 0)
+    return _create_global(cls, {Mode.PLAY: PlayBlock.RuntimeUpdate}, 0)
 
 
 @dataclass_transform()
 def _watch_runtime_update[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.WATCH: WatchBlock.RuntimeUpdate}, 0)
+    return _create_global(cls, {Mode.WATCH: WatchBlock.RuntimeUpdate}, 0)
 
 
 @dataclass_transform()
 def _preview_runtime_canvas[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeCanvas}, 0)
+    return _create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeCanvas}, 0)
 
 
 @dataclass_transform()
 def _tutorial_runtime_update[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeUpdate}, 0)
+    return _create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeUpdate}, 0)
 
 
 @dataclass_transform()
 def _runtime_touch_array[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PLAY: PlayBlock.RuntimeTouchArray}, 0)
+    return _create_global(cls, {Mode.PLAY: PlayBlock.RuntimeTouchArray}, 0)
 
 
 @dataclass_transform()
 def _runtime_skin_transform[T](cls: type[T]) -> T:
-    return create_global(
+    return _create_global(
         cls,
         {
             Mode.PLAY: PlayBlock.RuntimeSkinTransform,
@@ -145,7 +145,7 @@ def _runtime_skin_transform[T](cls: type[T]) -> T:
 
 @dataclass_transform()
 def _runtime_particle_transform[T](cls: type[T]) -> T:
-    return create_global(
+    return _create_global(
         cls,
         {
             Mode.PLAY: PlayBlock.RuntimeParticleTransform,
@@ -158,7 +158,7 @@ def _runtime_particle_transform[T](cls: type[T]) -> T:
 
 @dataclass_transform()
 def _runtime_background[T](cls: type[T]) -> T:
-    return create_global(
+    return _create_global(
         cls,
         {
             Mode.PLAY: PlayBlock.RuntimeBackground,
@@ -171,52 +171,69 @@ def _runtime_background[T](cls: type[T]) -> T:
 
 @dataclass_transform()
 def _play_runtime_ui[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PLAY: PlayBlock.RuntimeUI}, 0)
+    return _create_global(cls, {Mode.PLAY: PlayBlock.RuntimeUI}, 0)
 
 
 @dataclass_transform()
 def _watch_runtime_ui[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.WATCH: WatchBlock.RuntimeUI}, 0)
+    return _create_global(cls, {Mode.WATCH: WatchBlock.RuntimeUI}, 0)
 
 
 @dataclass_transform()
 def _tutorial_runtime_ui[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeUI}, 0)
+    return _create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeUI}, 0)
 
 
 @dataclass_transform()
 def _preview_runtime_ui[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeUI}, 0)
+    return _create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeUI}, 0)
 
 
 @dataclass_transform()
 def _play_runtime_ui_configuration[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PLAY: PlayBlock.RuntimeUIConfiguration}, 0)
+    return _create_global(cls, {Mode.PLAY: PlayBlock.RuntimeUIConfiguration}, 0)
 
 
 @dataclass_transform()
 def _watch_runtime_ui_configuration[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.WATCH: WatchBlock.RuntimeUIConfiguration}, 0)
+    return _create_global(cls, {Mode.WATCH: WatchBlock.RuntimeUIConfiguration}, 0)
 
 
 @dataclass_transform()
 def _tutorial_runtime_ui_configuration[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeUIConfiguration}, 0)
+    return _create_global(cls, {Mode.TUTORIAL: TutorialBlock.RuntimeUIConfiguration}, 0)
 
 
 @dataclass_transform()
 def _preview_runtime_ui_configuration[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeUIConfiguration}, 0)
+    return _create_global(cls, {Mode.PREVIEW: PreviewBlock.RuntimeUIConfiguration}, 0)
 
 
 @dataclass_transform()
 def _tutorial_instruction[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.TUTORIAL: TutorialBlock.TutorialInstruction}, 0)
+    return _create_global(cls, {Mode.TUTORIAL: TutorialBlock.TutorialInstruction}, 0)
 
 
 @dataclass_transform()
 def level_memory[T](cls: type[T]) -> T:
-    return create_global(
+    """Define level memory.
+
+    Level memory may be modified during gameplay in sequential callbacks (`preprocess`, `update_sequential`, `touch`).
+
+    Usage:
+        ```python
+        @level_memory
+        class LevelMemory:
+            variable: int
+
+        variable = level_data(Array[int, 10])
+
+        def f():
+            LevelMemory.variable = 1
+            variable[0] = 2
+        ```
+    """
+    return _create_global(
         cls,
         {
             Mode.PLAY: PlayBlock.LevelMemory,
@@ -229,7 +246,24 @@ def level_memory[T](cls: type[T]) -> T:
 
 @dataclass_transform()
 def level_data[T](cls: type[T]) -> T:
-    return create_global(
+    """Define level data.
+
+    Level data may only be modified during preprocessing.
+
+    Usage:
+        ```python
+        @level_data
+        class LevelData:
+            variable: int
+
+        variable = level_data(Array[int, 10])
+
+        def f():
+            LevelData.variable = 1
+            variable[0] = 2
+        ```
+    """
+    return _create_global(
         cls,
         {
             Mode.PLAY: PlayBlock.LevelData,
@@ -247,12 +281,12 @@ def level_data[T](cls: type[T]) -> T:
 
 @dataclass_transform()
 def _level_score[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PLAY: PlayBlock.LevelScore, Mode.WATCH: WatchBlock.LevelScore}, 0)
+    return _create_global(cls, {Mode.PLAY: PlayBlock.LevelScore, Mode.WATCH: WatchBlock.LevelScore}, 0)
 
 
 @dataclass_transform()
 def _level_life[T](cls: type[T]) -> T:
-    return create_global(cls, {Mode.PLAY: PlayBlock.LevelLife, Mode.WATCH: WatchBlock.LevelLife}, 0)
+    return _create_global(cls, {Mode.PLAY: PlayBlock.LevelLife, Mode.WATCH: WatchBlock.LevelLife}, 0)
 
 
 # engine_rom is handled by the compiler

sonolus/script/instruction.py

@@ -10,36 +10,64 @@ from sonolus.script.text import StandardText
 from sonolus.script.vec import Vec2
 
 
-class InstructionText(Record):
+class Instruction(Record):
+    """Tutorial instruction text.
+
+    Usage:
+        ```python
+        Instruction(id: int)
+        ```
+    """
+
     id: int
 
     def show(self):
+        """Show this instruction text."""
         show_instruction(self)
 
 
 class InstructionIcon(Record):
+    """Tutorial instruction icon.
+
+    Usage:
+        ```python
+        InstructionIcon(id: int)
+        ```
+    """
+
     id: int
 
     def paint(self, position: Vec2, size: float, rotation: float, z: float, a: float):
+        """Paint this instruction icon.
+
+        Args:
+            position: The position of the icon.
+            size: The size of the icon.
+            rotation: The rotation of the icon.
+            z: The z-index of the icon.
+            a: The alpha of the icon.
+        """
         _paint(self.id, position.x, position.y, size, rotation, z, a)
 
 
 @dataclass
-class InstructionTextInfo:
+class _InstructionTextInfo:
     name: str
 
 
 @dataclass
-class InstructionIconInfo:
+class _InstructionIconInfo:
     name: str
 
 
 def instruction(name: str) -> Any:
-    return InstructionTextInfo(name=name)
+    """Define an instruction with the given name."""
+    return _InstructionTextInfo(name=name)
 
 
 def instruction_icon(name: str) -> Any:
-    return InstructionIconInfo(name=name)
+    """Define an instruction icon with the given name."""
+    return _InstructionIconInfo(name=name)
 
 
 type TutorialInstructions = NewType("TutorialInstructions", Any)
@@ -48,6 +76,16 @@ type TutorialInstructionIcons = NewType("TutorialInstructionIcons", Any)
 
 @dataclass_transform()
 def instructions[T](cls: type[T]) -> T | TutorialInstructions:
+    """Decorator to define tutorial instructions.
+
+    Usage:
+        ```python
+        @instructions
+        class Instructions:
+            tap: StandardInstruction.TAP
+            other_instruction: InstructionText = instruction("Other Instruction")
+        ```
+    """
     if len(cls.__bases__) != 1:
         raise ValueError("Instructions class must not inherit from any class (except object)")
     instance = cls()
@@ -57,15 +95,15 @@ def instructions[T](cls: type[T]) -> T | TutorialInstructions:
             raise TypeError(f"Invalid annotation for instruction: {annotation}")
         annotation_type = annotation.__args__[0]
         annotation_values = annotation.__metadata__
-        if annotation_type is not InstructionText:
+        if annotation_type is not Instruction:
             raise TypeError(
                 f"Invalid annotation for instruction: {annotation}, expected annotation of type InstructionText"
             )
-        if len(annotation_values) != 1 or not isinstance(annotation_values[0], InstructionTextInfo):
+        if len(annotation_values) != 1 or not isinstance(annotation_values[0], _InstructionTextInfo):
             raise TypeError(f"Invalid annotation for instruction: {annotation}, expected a single annotation value")
         instruction_name = annotation_values[0].name
         names.append(instruction_name)
-        setattr(instance, name, InstructionText(i))
+        setattr(instance, name, Instruction(i))
     instance._instructions_ = names
     instance._is_comptime_value_ = True
     return instance
@@ -73,6 +111,16 @@ def instructions[T](cls: type[T]) -> T | TutorialInstructions:
 
 @dataclass_transform()
 def instruction_icons[T](cls: type[T]) -> T | TutorialInstructionIcons:
+    """Decorator to define tutorial instruction icons.
+
+    Usage:
+        ```python
+        @instruction_icons
+        class InstructionIcons:
+            hand: StandardInstructionIcon.HAND
+            other_icon: InstructionIcon = instruction_icon("Other Icon")
+        ```
+    """
     if len(cls.__bases__) != 1:
         raise ValueError("Instruction icons class must not inherit from any class (except object)")
     instance = cls()
@@ -86,7 +134,7 @@ def instruction_icons[T](cls: type[T]) -> T | TutorialInstructionIcons:
             raise TypeError(
                 f"Invalid annotation for instruction icon: {annotation}, expected annotation of type InstructionIcon"
             )
-        if len(annotation_values) != 1 or not isinstance(annotation_values[0], InstructionIconInfo):
+        if len(annotation_values) != 1 or not isinstance(annotation_values[0], _InstructionIconInfo):
             raise TypeError(
                 f"Invalid annotation for instruction icon: {annotation}, expected a single annotation value"
             )
@@ -99,23 +147,27 @@ def instruction_icons[T](cls: type[T]) -> T | TutorialInstructionIcons:
 
 
 class StandardInstruction:
-    TAP = Annotated[InstructionText, instruction(StandardText.TAP)]
-    TAP_HOLD = Annotated[InstructionText, instruction(StandardText.TAP_HOLD)]
-    TAP_RELEASE = Annotated[InstructionText, instruction(StandardText.TAP_RELEASE)]
-    TAP_FLICK = Annotated[InstructionText, instruction(StandardText.TAP_FLICK)]
-    TAP_SLIDE = Annotated[InstructionText, instruction(StandardText.TAP_SLIDE)]
-    HOLD = Annotated[InstructionText, instruction(StandardText.HOLD)]
-    HOLD_SLIDE = Annotated[InstructionText, instruction(StandardText.HOLD_SLIDE)]
-    HOLD_FOLLOW = Annotated[InstructionText, instruction(StandardText.HOLD_FOLLOW)]
-    RELEASE = Annotated[InstructionText, instruction(StandardText.RELEASE)]
-    FLICK = Annotated[InstructionText, instruction(StandardText.FLICK)]
-    SLIDE = Annotated[InstructionText, instruction(StandardText.SLIDE)]
-    SLIDE_FLICK = Annotated[InstructionText, instruction(StandardText.SLIDE_FLICK)]
-    AVOID = Annotated[InstructionText, instruction(StandardText.AVOID)]
-    JIGGLE = Annotated[InstructionText, instruction(StandardText.JIGGLE)]
+    """Standard instructions."""
+
+    TAP = Annotated[Instruction, instruction(StandardText.TAP)]
+    TAP_HOLD = Annotated[Instruction, instruction(StandardText.TAP_HOLD)]
+    TAP_RELEASE = Annotated[Instruction, instruction(StandardText.TAP_RELEASE)]
+    TAP_FLICK = Annotated[Instruction, instruction(StandardText.TAP_FLICK)]
+    TAP_SLIDE = Annotated[Instruction, instruction(StandardText.TAP_SLIDE)]
+    HOLD = Annotated[Instruction, instruction(StandardText.HOLD)]
+    HOLD_SLIDE = Annotated[Instruction, instruction(StandardText.HOLD_SLIDE)]
+    HOLD_FOLLOW = Annotated[Instruction, instruction(StandardText.HOLD_FOLLOW)]
+    RELEASE = Annotated[Instruction, instruction(StandardText.RELEASE)]
+    FLICK = Annotated[Instruction, instruction(StandardText.FLICK)]
+    SLIDE = Annotated[Instruction, instruction(StandardText.SLIDE)]
+    SLIDE_FLICK = Annotated[Instruction, instruction(StandardText.SLIDE_FLICK)]
+    AVOID = Annotated[Instruction, instruction(StandardText.AVOID)]
+    JIGGLE = Annotated[Instruction, instruction(StandardText.JIGGLE)]
 
 
 class StandardInstructionIcon:
+    """Standard instruction icons."""
+
     HAND = Annotated[InstructionIcon, instruction_icon("#HAND")]
     ARROW = Annotated[InstructionIcon, instruction_icon("#ARROW")]
 
@@ -139,13 +191,15 @@ def _paint(
     rotation: float,
     z: float,
     a: float,
-):
+) -> None:
     raise NotImplementedError()
 
 
-def show_instruction(inst: InstructionText, /):
+def show_instruction(inst: Instruction, /):
+    """Show the given instruction text."""
     _TutorialInstruction.text_id = inst.id
 
 
 def clear_instruction():
+    """Clear the current instruction text."""
     _TutorialInstruction.text_id = -1