Scrawl

https://github.com/streetartist/scrawl
Admin
Scrawl is a Python game engine based on Pygame, offering a Scratch-like development experience with...
Tokens:3,832
Snippets:19
Trust Score:7
License:GPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install and Upgrade Scrawl Engine

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Instructions for installing and upgrading the Scrawl game engine using Python's package installer, pip.

```bash
pip install scrawl-engine
```

```bash
pip install --upgrade scrawl-engine
```

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

### Incomplete Scrawl Import Example

Source: https://github.com/streetartist/scrawl/blob/main/README.md

This snippet shows basic imports for Scrawl and the `time` module, but lacks further code to demonstrate functionality. It serves as an incomplete example of setting up a Scrawl script, indicating the initial steps for importing necessary components.

```Python
from scrawl import *
import time
```

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

### Install and Update Scrawl Engine

Source: https://github.com/streetartist/scrawl/blob/main/README_zh.md

Commands to install the Scrawl game engine using pip and to upgrade it to the latest version, ensuring you have the latest features and bug fixes.

```Bash
pip install scrawl-engine
```

```Bash
pip install --upgrade scrawl-engine
```

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

### Basic Scrawl Game with a Walking Cat Sprite

Source: https://github.com/streetartist/scrawl/blob/main/README.md

This simple example illustrates the fundamental structure of a Scrawl game. It shows how to create a `Game` instance, define a custom `Sprite` (MyCat) inheriting from `Cat`, implement a main coroutine (`@as_main`) for continuous animation, and set up a `Scene` to add the sprite before running the game. This serves as a minimal working example for Scrawl.

```Python
from scrawl import Game, Scene, Sprite, Cat, as_main

# Create game instance
game = Game()

class MyCat(Cat):
    def __init__(self):
        super().__init__()

    @as_main
    def main1(self):
        while True:
            self.walk()
            yield 500

# Define scene
class MyScene(Scene):
    def __init__(self):
        super().__init__()
        # Add sprite
        cat = MyCat()
        self.add_sprite(cat)

# Run game
game.set_scene(MyScene())
game.run()
```

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

### Scrawl Game Example: Witch and Bat Interaction

Source: https://github.com/streetartist/scrawl/blob/main/README_zh.md

A comprehensive example demonstrating sprite creation, costume management, clone behavior, collision handling, and keyboard input within the Scrawl engine. It simulates a game where a witch interacts with bats and fireballs, showcasing various core features.

```Python
from scrawl import *
import pygame

# svg 文件来自 https://scratch.mit.edu/projects/239626199/editor/

# 创建游戏实例
game = Game()

class Bat(Sprite):
    def __init__(self):
        super().__init__()
        self.name = "Bat"
        self.add_costume("costume1", pygame.image.load("bat2-b.svg").convert_alpha())
        self.add_costume("costume2", pygame.image.load("bat2-a.svg").convert_alpha())
        self.visible = False
        self.set_size(0.5)

    @as_clones
    def clones1(self):
        self.pos = pygame.Vector2(400, 300)
        self.face_random_direction()
        self.move(400)
        self.face_towards("Witch")
        self.visible = True
        while True:
            self.next_costume()
            yield 300

    @as_clones
    def clones2(self):
        while True:
            self.move(5)
            yield 200

    @as_main
    def main1(self):
        while True:
            yield 3000
            # 添加蝙蝠
            self.clone()

    @handle_edge_collision()
    def finish(self):
        self.delete_self()

    @handle_sprite_collision("FireBall")
    def hit_fireball(self, other):
        self.delete_self()

    @handle_sprite_collision("Witch")
    def hit_witch(self, other):
        self.delete_self()

class FireBall(Sprite):
    def __init__(self):
        super().__init__()
        self.name = "FireBall"
        self.add_costume("costume1", pygame.image.load("ball-a.svg").convert_alpha())
        self.visible = False
        self.set_size(0.2)

    @as_clones
    def clones1(self):
        self.visible = True
        while True:
            self.move(10)
            yield 100

    @handle_edge_collision()
    def finish(self):
        self.delete_self()

class Witch(Sprite):
    def __init__(self):
        super().__init__()
        self.name = "Witch"
        self.add_costume("costume1", pygame.image.load("witch.svg").convert_alpha())
        self.fireball = FireBall()

    @on_key(pygame.K_s, "held")
    def right_held(self):
        self.turn_right(2)

    @on_key(pygame.K_d, "held")
    def left_held(self):
        self.turn_left(2)

    @on_key(pygame.K_SPACE, "held")
    def space_pressed(self):
        self.fireball.direction = self.direction
        self.clone(self.fireball)

# 定义场景
class MyScene(Scene):
    def __init__(self):
        super().__init__()
        bat = Bat()
        self.add_sprite(bat)
        witch = Witch()
        self.add_sprite(witch)

# 运行游戏
game.set_scene(MyScene())
game.run(fps=60)
```

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

### Creating a Complex Game with Scrawl Sprites and Event Handling

Source: https://github.com/streetartist/scrawl/blob/main/README.md

This comprehensive example demonstrates building a game with multiple interactive sprites (Bat, FireBall, Witch) using Scrawl. It showcases sprite creation, costume management, clone behavior with `@as_clones`, main game logic with `@as_main`, and event handling for collisions (`@handle_edge_collision`, `@handle_sprite_collision`) and key presses (`@on_key`). It illustrates how to manage sprite interactions, animations, and game flow within the Scrawl framework.

```Python
from scrawl import *
import pygame

# svg files from https://scratch.mit.edu/projects/239626199/editor/

# Create game instance
game = Game()

class Bat(Sprite):
    def __init__(self):
        super().__init__()
        self.name = "Bat"
        self.add_costume("costume1", pygame.image.load("bat2-b.svg").convert_alpha())
        self.add_costume("costume2", pygame.image.load("bat2-a.svg").convert_alpha())
        self.visible = False
        self.set_size(0.5)

    @as_clones
    def clones1(self):
        self.pos = pygame.Vector2(400, 300)
        self.face_random_direction()
        self.move(400)
        self.face_towards("Witch")
        self.visible = True
        while True:
            self.next_costume()
            yield 300

    @as_clones
    def clones2(self):
        while True:
            self.move(5)
            yield 200

    @as_main
    def main1(self):
        while True:
            yield 3000
            # Add bat
            self.clone()

    @handle_edge_collision()
    def finish(self):
        self.delete_self()

    @handle_sprite_collision("FireBall")
    def hit_fireball(self, other):
        self.delete_self()

    @handle_sprite_collision("Witch")
    def hit_witch(self, other):
        self.delete_self()

class FireBall(Sprite):
    def __init__(self):
        super().__init__()
        self.name = "FireBall"
        self.add_costume("costume1", pygame.image.load("ball-a.svg").convert_alpha())
        self.visible = False
        self.set_size(0.2)

    @as_clones
    def clones1(self):
        self.visible = True
        while True:
            self.move(10)
            yield 100

    @handle_edge_collision()
    def finish(self):
        self.delete_self()

class Witch(Sprite):
    def __init__(self):
        super().__init__()
        self.name = "Witch"
        self.add_costume("costume1", pygame.image.load("witch.svg").convert_alpha())
        self.fireball = FireBall()

    @on_key(pygame.K_s, "held")
    def right_held(self):
        self.turn_right(2)

    @on_key(pygame.K_d, "held")
    def left_held(self):
        self.turn_left(2)

    @on_key(pygame.K_SPACE, "held")
    def space_pressed(self):
        self.fireball.direction = self.direction
        self.clone(self.fireball)

# Define scene
class MyScene(Scene):
    def __init__(self):
        super().__init__()
        bat = Bat()
        self.add_sprite(bat)
        witch = Witch()
        self.add_sprite(witch)

# Run game
game.set_scene(MyScene())
game.run(fps=60)
```

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

### Scrawl Basic Sprite Movement: Cat Walk

Source: https://github.com/streetartist/scrawl/blob/main/README_zh.md

A simple example showcasing how to create a custom Cat sprite and define its main behavior using the `@as_main` decorator to make it walk continuously within a Scrawl game scene. This illustrates fundamental sprite animation.

```Python
from scrawl import Game, Scene, Sprite, Cat, as_main

# 创建游戏实例
game = Game()

class MyCat(Cat):
    def __init__(self):
        super().__init__()

    @as_main
    def main1(self):
        while True:
            self.walk()
            yield 500

# 定义场景
class MyScene(Scene):
    def __init__(self):
        super().__init__()
        # 添加精灵
        cat = MyCat()
        self.add_sprite(cat)

# 运行游戏
game.set_scene(MyScene())
game.run()
```

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

### Scrawl Advanced Sprite Behavior: Ball Cloning and Broadcast

Source: https://github.com/streetartist/scrawl/blob/main/README_zh.md

An example illustrating dynamic sprite cloning, continuous movement and rotation, color changes, and the use of a particle system. It also demonstrates inter-component communication via broadcast messages within the Scrawl engine for complex interactions.

```Python
from scrawl import *
import time

# 创建游戏实例
game = Game()

class Ball(Sprite):
    def __init__(self):
        super().__init__()

    @as_main
    def main1(self):
        while True:
            self.turn_left(10)
            self.move(10)
            yield 100
            self.clone()

    @as_clones
    def clones1(self):
        while True:
            self.turn_right(10)
            self.move(100)
            self.change_color_random()
            yield 1000

    @handle_broadcast("event")
    def event1(self):
        self.say("hello")

# 定义场景
class MyScene(Scene):
    def __init__(self):
        super().__init__()
        # 添加精灵
        ball = Ball()
        self.add_sprite(ball)

    @as_main
    def main1(self):
        while True:
            # 添加粒子系统
            explosion = ParticleSystem(400, 300)
            self.add_particles(explosion)  # 将粒子系统添加到场景
            self.broadcast("event")
            yield 3000
```

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

### Scrawl Core Classes API Reference (Game, Scene, Sprite)

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Detailed API documentation for the fundamental Scrawl classes: `Game`, `Scene`, and `Sprite`. It covers their constructors, key properties, methods, and associated decorators like `@as_main` and `@as_clones`.

```APIDOC
Game Class:
  Main game controller responsible for initialization and running game loop.
  __init__(width: int, height: int, title: str, font_path: str = None, font_size: int = 20, fullscreen: bool = False)
    - width: Width of the game window.
    - height: Height of the game window.
    - title: Title of the game window.
    - font_path: Path to a custom font file (optional).
    - font_size
```

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

### Basic Scrawl Game Structure and Execution

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Illustrates the fundamental components of a Scrawl game, including the `Game` instance, `Ball` (Sprite) and `MyScene` (Scene) class definitions with their main behaviors, clone behaviors, and event handling. It demonstrates sprite movement, cloning, scene management, and broadcasting events.

```python
game = Game()

class Ball(Sprite):
    def __init__(self):
        super().__init__()

    @as_main
    def main1(self):
        while True:
            self.turn_left(10)
            self.move(10)
            yield 100
            self.clone()

    @as_clones
    def clones1(self):
        while True:
            self.turn_right(10)
            self.move(100)
            self.change_color_random()
            yield 1000

    @handle_broadcast("event")
    def event1(self):
        self.say("hello")

class MyScene(Scene):
    def __init__(self):
        super().__init__()
        ball = Ball()
        self.add_sprite(ball)

    @as_main
    def main1(self):
        while True:
            explosion = ParticleSystem(400, 300)
            self.add_particles(explosion)
            self.broadcast("event")
            yield 3000

game.set_scene(MyScene())
game.run()
```

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

### Broadcast and Handle Events in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Demonstrates how to broadcast custom events within the game engine and how to define methods that automatically handle these events using a decorator, facilitating communication between game entities.

```python
# Broadcast event
self.broadcast("gameover")
# Handle broadcast event
@handle_broadcast("gameover")
def on_gameover(self):
    self.visible = True
```

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

### Adding Particle Systems in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Illustrates how to create and add dynamic particle effects to a scene. This snippet shows how to instantiate a `ParticleSystem` with parameters like position, particle count, and the lifespan range of individual particles.

```python
# Create particle system at specified position
self.scene.add_particles(
    ParticleSystem(
        x=100, 
        y=100, 
        count=50,
        life_range=(500, 1500)
    )
)
```

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

### Enabling Debug Mode and Logging in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Shows how to activate the game's debug mode during runtime initialization and how to log custom debug messages. This is useful for displaying internal game state and troubleshooting during development.

```python
game.run(debug=True)  # Enable debug mode
# Log debug information
game.log_debug("Sprite created")
```

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

### Configuring Game Fonts in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Demonstrates how to set global font properties for the game, including specifying a font file path and size during game initialization. This supports various font types, including those for non-Latin characters like Chinese.

```python
game = Game(
    font_path="Simhei.ttf",  # Supports Chinese fonts
    font_size=20
)
```

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

### Creating Sprite Clones in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Illustrates how to create new instances (clones) of existing sprites. This can be used to duplicate the current sprite or any other specified sprite, enabling dynamic object generation in a game.

```python
# Clone self
self.clone()
# Clone other sprite
self.clone(other_sprite)
```

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

### Implementing Pen Drawing Effects in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Explains how to enable drawing functionality for a sprite, allowing it to leave trails as it moves. This includes setting the pen's color and size, and a method to clear all drawn trails from the screen.

```python
# Enable pen
self.pen_down = True
self.pen_color = (255, 0, 0)
self.pen_size = 3
# Automatically record path when moving
self.move(100)
# Clear pen trails
self.clear_pen()
```

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

### Implementing Physics-Based Sprites in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Shows how to create sprites that interact with a physics engine by inheriting from `PhysicsSprite`. This allows defining properties such as initial velocity, gravitational pull, and elasticity for realistic movement.

```python
class PhysicsBall(PhysicsSprite):
    def __init__(self):
        super().__init__()
        self.velocity = pygame.Vector2(0, 5)
        self.gravity = pygame.Vector2(0, 0.2)
        self.elasticity = 0.8  # Elasticity coefficient
```

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

### Defining Clone-Specific Behavior in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Shows how to define unique logic that applies specifically to cloned sprites. The `@as_clones` decorator marks a method to be executed by clones, allowing them to perform independent actions like movement or animation.

```python
class Bat(Sprite):
    @as_clones  # Mark as clone task
    def clones_behavior(self):
        self.visible = True
        while True:
            self.move(5)
            yield 200  # Move every 200ms
```

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

### Managing Sprite Costumes (Images) in Python

Source: https://github.com/streetartist/scrawl/blob/main/README.md

Explains how to add multiple image costumes to a sprite and programmatically switch between them. This functionality is essential for animating sprites or changing their appearance based on game state.

```python
self.add_costume("costume1", pygame.image.load("cat1.svg"))
self.add_costume("costume2", pygame.image.load("cat2.svg"))
self.switch_costume("costume1")  # Switch costume
self.next_costume()  # Switch to next costume
```
Tokens:
Raw