### Initialize a Basic Batgrl Application

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/pong_tutorial.rst

This snippet demonstrates the minimal setup for a batgrl application. It defines a `Pong` class inheriting from `App` and includes an `on_start` method, which is the entry point for app initialization. The `if __name__ == "__main__":` block ensures the app runs when the script is executed.

```python
from batgrl.app import App


class Pong(App):
    async def on_start(self):
        pass


if __name__ == "__main__":
    Pong().run()
```

--------------------------------

### Partial Batgrl Pong Setup: Paddle Movement and Initial App Structure

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/pong_tutorial.rst

This snippet provides a partial view of a `batgrl` Pong game implementation. It shows the `on_key` method for paddle vertical movement, including boundary checks. It also outlines the initial `Pong` `App` class setup, demonstrating how to add basic game elements like paddles, a divider, and score labels to the game field, without including the ball or full game logic.

```python
                self.y += 1

            if self.y < 0:
                self.y = 0
            elif self.y > FIELD_HEIGHT - PADDLE_HEIGHT:
                self.y = FIELD_HEIGHT - PADDLE_HEIGHT


    class Pong(App):
        async def on_start(self):
            game_field = Pane(size=(FIELD_HEIGHT, FIELD_WIDTH), bg_color=GREEN)
            center = FIELD_HEIGHT // 2 - PADDLE_HEIGHT // 2
            left_paddle = Paddle(
                up="w",
                down="s",
                size=(PADDLE_HEIGHT, PADDLE_WIDTH),
                pos=(center, 1),
                bg_color=BLUE,
            )
            right_paddle = Paddle(
                up="up",
                down="down",
                size=(PADDLE_HEIGHT, PADDLE_WIDTH),
                pos=(center, FIELD_WIDTH - 2),
                bg_color=BLUE,
            )
            divider = Pane(
                size=(1, 1),
                size_hint={"height_hint": 1.0},
                pos_hint={"x_hint": 0.5},
                bg_color=BLUE,
            )
            left_score_label = Text(
                size=(1, 5),
                pos=(1, 1),
                pos_hint={"x_hint": 0.25},
            )
            right_score_label = Text(
                size=(1, 5),
                pos=(1, 1),
                pos_hint={"x_hint": 0.75},
            )

            game_field.add_gadgets(
                left_paddle,
                right_paddle,
                divider,
                left_score_label,
                right_score_label,
            )
            self.add_gadget(game_field)


    if __name__ == "__main__":
        Pong().run()
```

--------------------------------

### Run Terminal Particle Simulator

Source: https://github.com/salt-die/batgrl/blob/main/examples/advanced/sandbox/README.md

This command executes the `sandbox` module as a script, launching the terminal-based particle simulator. Ensure Python is installed and the `sandbox` module is available in your Python environment.

```Shell
python -m sandbox
```

--------------------------------

### Complete Asynchronous Batgrl Pong Game with Ball and Physics

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/pong_tutorial.rst

This comprehensive Python snippet presents a full, runnable `batgrl` Pong game. It includes all necessary imports, the `Paddle` class with key-based movement, and an extended `Pong` `App` class. The `on_start` method is asynchronous, enabling continuous updates for the ball's position and implementing core game mechanics such as score reset and initial paddle collision detection. This example demonstrates a complete `batgrl` application with interactive elements and real-time updates.

```python
    import asyncio

    from batgrl.app import App
    from batgrl.colors import BLUE, GREEN
    from batgrl.gadgets.pane import Pane
    from batgrl.gadgets.text import Text

    FIELD_HEIGHT = 25
    FIELD_WIDTH = 100
    PADDLE_HEIGHT = 5
    PADDLE_WIDTH = 1


    class Paddle(Pane):
        def __init__(self, up, down, **kwargs):
            self.up = up
            self.down = down
            super().__init__(**kwargs)

        def on_key(self, key_event):
            if key_event.key == self.up:
                self.y -= 1
            elif key_event.key == self.down:
                self.y += 1

            if self.y < 0:
                self.y = 0
            elif self.y > FIELD_HEIGHT - PADDLE_HEIGHT:
                self.y = FIELD_HEIGHT - PADDLE_HEIGHT


    class Pong(App):
        async def on_start(self):
            game_field = Pane(size=(FIELD_HEIGHT, FIELD_WIDTH), bg_color=GREEN)
            center = FIELD_HEIGHT // 2 - PADDLE_HEIGHT // 2
            left_paddle = Paddle(
                up="w",
                down="s",
                size=(PADDLE_HEIGHT, PADDLE_WIDTH),
                pos=(center, 1),
                bg_color=BLUE,
            )
            right_paddle = Paddle(
                up="up",
                down="down",
                size=(PADDLE_HEIGHT, PADDLE_WIDTH),
                pos=(center, FIELD_WIDTH - 2),
                bg_color=BLUE,
            )
            divider = Pane(
                size=(1, 1),
                size_hint={"height_hint": 1.0},
                pos_hint={"x_hint": 0.5},
                bg_color=BLUE,
            )
            left_score_label = Text(
                size=(1, 5),
                pos=(1, 1),
                pos_hint={"x_hint": 0.25},
            )
            right_score_label = Text(
                size=(1, 5),
                pos=(1, 1),
                pos_hint={"x_hint": 0.75},
            )
            ball = Pane(size=(1, 2), bg_color=BLUE)

            game_field.add_gadgets(
                left_paddle,
                right_paddle,
                divider,
                left_score_label,
                right_score_label,
                ball,
            )
            self.add_gadget(game_field)

            left_score = right_score = 0
            y_pos = FIELD_HEIGHT / 2
            x_pos = FIELD_WIDTH / 2 - 1
            y_vel = 0.0
            x_vel = 1.0
            speed = 0.04

            def reset():
                nonlocal y_pos, x_pos, y_vel, x_vel, speed
                y_pos = FIELD_HEIGHT / 2
                x_pos = FIELD_WIDTH / 2 - 1
                y_vel = 0.0
                x_vel = 1.0
                speed = 0.04
                left_score_label.add_str(f"{left_score:^5}")
                right_score_label.add_str(f"{right_score:^5}")

            def bounce_paddle(paddle):
                nonlocal x_pos, y_vel, x_vel, speed
                x_pos -= 2 * x_vel
                x_sgn = 1 if x_vel > 0 else -1
                center_y = paddle.height // 2
                intersect = max(min(paddle.y + center_y - ball.y, 0.95), -0.95)
```

--------------------------------

### Prepare for Layout with Batgrl Size and Position Hints

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/pong_tutorial.rst

This snippet introduces the concept of size and position hints for flexible gadget layout, which automatically adjusts with parent resizing. It also imports the `Text` gadget, indicating its future use for displaying scores, and continues the `Paddle` class definition, though the `on_key` method is incomplete in the provided text.

```python
from batgrl.app import App
from batgrl.colors import BLUE, GREEN
from batgrl.gadgets.pane import Pane
from batgrl.gadgets.text import Text

FIELD_HEIGHT = 25
FIELD_WIDTH = 100
PADDLE_HEIGHT = 5
PADDLE_WIDTH = 1


class Paddle(Pane):
    def __init__(self, up, down, **kwargs):
        self.up = up
        self.down = down
        super().__init__(**kwargs)

    def on_key(self, key_event):
        if key_event.key == self.up:
            self.y -= 1
        elif key_event.key == self.down:
```

--------------------------------

### Gadget Size and Position Hinting

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/gadgets.rst

Explains how gadgets can dynamically adjust their size and position relative to their parent using hints, and how the `anchor` attribute refines positioning.

```APIDOC
Gadget Size and Position Hints:
  Size Hint:
    Description: If non-None, gadget size is a proportion of its parent. Updates on parent resize.
  Position Hint:
    Description: If non-None, gadget positions itself at a proportion of its parent's size.
    Anchor:
      Description: Determines which point in the gadget is aligned with the position hint.
      Default: "center"
```

--------------------------------

### Implement Keyboard Input for Batgrl Paddles

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/pong_tutorial.rst

This snippet introduces custom gadget behavior by subclassing `Pane` to create a `Paddle` class. It demonstrates how to handle keyboard input using the `on_key` method to move paddles vertically and constrain their movement within the game field boundaries. Two paddles are then added to the game field.

```python
from batgrl.app import App
from batgrl.colors import BLUE, GREEN
from batgrl.gadgets.pane import Pane

FIELD_HEIGHT = 25
FIELD_WIDTH = 100
PADDLE_HEIGHT = 5
PADDLE_WIDTH = 1


class Paddle(Pane):
    def __init__(self, up, down, **kwargs):
        self.up = up
        self.down = down
        super().__init__(**kwargs)

    def on_key(self, key_event):
        if key_event.key == self.up:
            self.y -= 1
        elif key_event.key == self.down:
            self.y += 1

        if self.y < 0:
            self.y = 0
        elif self.y > FIELD_HEIGHT - PADDLE_HEIGHT:
            self.y = FIELD_HEIGHT - PADDLE_HEIGHT


class Pong(App):
    async def on_start(self):
        game_field = Pane(size=(FIELD_HEIGHT, FIELD_WIDTH), bg_color=GREEN)
        center = FIELD_HEIGHT // 2 - PADDLE_HEIGHT // 2
        left_paddle = Paddle(
            up="w",
            down="s",
            size=(PADDLE_HEIGHT, PADDLE_WIDTH),
            pos=(center, 1),
            bg_color=BLUE,
        )
        right_paddle = Paddle(
            up="up",
            down="down",
            size=(PADDLE_HEIGHT, PADDLE_WIDTH),
            pos=(center, FIELD_WIDTH - 2),
            bg_color=BLUE,
        )

        game_field.add_gadgets(left_paddle, right_paddle)
        self.add_gadget(game_field)


if __name__ == "__main__":
    Pong().run()
```

--------------------------------

### Render a Green Play Field with Batgrl Pane

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/pong_tutorial.rst

This code snippet shows how to add basic graphics to the batgrl application. It uses the `Pane` gadget to create a rectangular game field with a green background color, demonstrating how to instantiate and add gadgets to the app's display tree.

```python
from batgrl.app import App
from batgrl.colors import GREEN
from batgrl.gadgets.pane import Pane

FIELD_HEIGHT = 25
FIELD_WIDTH = 100


class Pong(App):
    async def on_start(self):
        game_field = Pane(size=(FIELD_HEIGHT, FIELD_WIDTH), bg_color=GREEN)
        self.add_gadget(game_field)


if __name__ == "__main__":
    Pong().run()
```

--------------------------------

### Gadget Input Event Handling

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/gadgets.rst

Describes the methods available on each gadget for responding to input events, and the mechanism for signaling event handling completion.

```APIDOC
Gadget Event Methods:
  on_key():
    Description: Responds to key input events.
    Returns: bool - True if the event was handled, stopping further dispatch.
  on_mouse():
    Description: Responds to mouse input events.
    Returns: bool - True if the event was handled, stopping further dispatch.
  on_paste():
    Description: Responds to paste input events.
    Returns: bool - True if the event was handled, stopping further dispatch.
```

--------------------------------

### Python Pong Game Loop and Collision Logic

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/pong_tutorial.rst

This Python code snippet illustrates the main game loop for a Pong game, including calculations for ball movement, collision detection with paddles and the playfield boundaries, score updates, and game resets. It utilizes `asyncio.sleep` to control the game speed.

```python
                normalized = intersect / center_y
                y_vel = -normalized
                x_vel = -x_sgn * (1 - normalized**2) ** 0.5
                speed = max(0, speed - 0.001)

            reset()
            while True:
                # Update ball position.
                y_pos += y_vel
                x_pos += x_vel

                # Does ball collide with a paddle?
                if ball.collides_gadget(left_paddle):
                    bounce_paddle(left_paddle)
                elif ball.collides_gadget(right_paddle):
                    bounce_paddle(right_paddle)

                # Bounce off the top or bottom of the play field.
                if y_pos < 0 or y_pos >= FIELD_HEIGHT:
                    y_vel *= -1
                    y_pos += 2 * y_vel

                # If out of bounds, update the score.
                if x_pos < 0:
                    right_score += 1
                    reset()
                elif x_pos >= FIELD_WIDTH:
                    left_score += 1
                    reset()

                ball.y = int(y_pos)
                ball.x = int(x_pos)

                await asyncio.sleep(speed)


    if __name__ == "__main__":
        Pong().run()
```

--------------------------------

### Gadget Tree Manipulation and Event Handling API

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/gadget_tree.rst

Documentation for methods available on gadgets within the batgrl gadget tree, covering tree modification, traversal, rendering, and input event handling. These methods define how gadgets interact within the hierarchical structure and respond to system events.

```APIDOC
Gadget Tree Modification Methods:
  add_gadget(): Add a gadget as a child.
  add_gadgets(): Add an iterable of gadgets or add multiple gadgets as children.
  remove_gadget(): Remove a child gadget.
  prolicide(): Recursively remove all child gadgets.
  destroy(): Remove a gadget from its parent and recursively remove all its children.

Lifecycle Hooks:
  on_add(): Called when a gadget is added to the gadget tree.
  on_remove(): Called when a gadget is removed from the gadget tree.

Traversal Methods:
  walk(): Iterate over all descendents of a gadget (preorder traversal).
  walk_reverse(): Iterate over all descendents of a gadget (reverse postorder traversal).
  ancestors(): Iterate over all ancestors of a gadget.

Rendering Methods:
  pull_to_front(): Move a gadget to the end of `children` making sure it is drawn after all its siblings.

Input Event Handlers:
  on_key(): Handles key events.
  on_mouse(): Handles mouse events.
  on_paste(): Handles paste events.
  on_terminal_focus(): Handles focus events.
```

--------------------------------

### Specific Gadget Implementations

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/gadgets.rst

Details various specialized gadget types derived from the base gadget, highlighting their unique functionalities and attributes.

```APIDOC
Pane:
  Description: A gadget with a background color.
  Attributes:
    alpha: Transparency modifier.

Graphics:
  Description: A gadget for arbitrary RGBA textures.

Text:
  Description: The most general gadget.
  State: An array of cells, each carrying terminal character attributes (character, bold, foreground color).
```

--------------------------------

### Gadget Core Attributes and Properties

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/gadgets.rst

Describes the fundamental attributes of a base gadget, including its role as a container and properties like transparency, visibility, and event dispatching.

```APIDOC
Gadget:
  Attributes:
    size: Size of the gadget.
    position: Position of the gadget.
    children: Reference to child gadgets.
    is_transparent: bool - Determines if gadgets beneath are rendered.
    is_visible: bool - Determines if the gadget is rendered.
    is_enabled: bool - Determines if input events are dispatched.
```

--------------------------------

### Gadget Collision Detection

Source: https://github.com/salt-die/batgrl/blob/main/docs/user/gadgets.rst

Outlines methods for determining spatial relationships between a gadget and points or other gadgets, including coordinate conversion.

```APIDOC
Gadget Collision Methods:
  collides_point(point):
    Description: Determines if a given point is within the gadget's visible region.
    Parameters:
      point: Coordinates of the point.
    Returns: bool
  to_local(point):
    Description: Converts a point from absolute coordinates to the gadget's local coordinates.
    Parameters:
      point: Absolute coordinates.
    Returns: Local coordinates.
  collides_gadget(other_gadget):
    Description: Determines if one gadget overlaps another.
    Parameters:
      other_gadget: The other gadget to check for collision.
    Returns: bool
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.