Pop

A simple 2D game engine

NAME

Pop

SYNOPSIS

use Pop;
use Pop::Inputs;
use Pop::Graphics;

# Create your entities, maybe with Pop::Entities

Pop.new: title => 'Revenge of the Avengers';

Pop.update: -> $delta-in-seconds {
    # Run update systems

    # Inputs are automatically read at the beginning
    # of the main loop and exposed through Pop::Inputs
    Pop.stop if Pop::Inputs.keyboard: 'ESCAPE';
}

Pop.render: {
    # Run rendering systems.

    # Screen buffers will be automatically swapped after this block

    given Pop::Graphics {
        .point: ( (^.width).pick, (^.height).pick ), (^256).pick xx 3;
    }
}

# Run the main loop
Pop.run;

DESCRIPTION

Pop is an experimental 2D game development framework for Raku. It has been inspired by frameworks like LÓVE2D and Pico-8, and by others of a similar nature. It runs on SDL2 using custom bindings.

This project is still in its infancy, and the interface might change without warning. Any changes (breaking or otherwise) will still be reported in the change log, so that is the first place to check before updating.

CONCEPTS

Singletons

Most core classes (including the main Pop game class as well as helpers like Pop::Graphics and Pop::inputs) are implemented as globally available singletons. This means that, unless specific parameters need to be set during initialisation, there is no need to manually construct them and pass references to them, which should help simplify game code.

The caveat to this is that, since they will be constructed automatically if needed, any manual initialisation needs to be done as early as possible.

Configuration

Most default values used throughout Pop can be specified via the global Pop::Config singleton (see the documentation of that module for more details).

The values in Pop::Config will be read from a file named config.toml in the same directory as the mainline entrypoint. To read the global configuration from a different path, pass that path to Pop::Config.new as early as possible.

METHODS

new

method new (|c) returns Pop

Initialises a new global game object.

This function will be called automatically when any method is called on Pop, so it should be called as early as possible unless the default values are appropriate.

The parameters passed in will be forwarded to the initialisation of the global Pop::Graphics singleton. See that module for more details about acceptable parameters and their meanings.

Default values are those specified by Pop::Config. See that module for more details.

run

method new (
    :$fps = 60,
    :$dt,
) returns Nil

Starts the execution a game's main loop. The main loop will continue to execute until stop is called, either directly or through handle-input.

The default main loop has roughly the following stages:

handle-input is called, to process input events.
The update block is executed as many times as needed.
If the $dt parameter was set, then the block will be called as long as that amount of time has accumulated since the last time it was called. Otherwise, the block will be called once with however much time has elapsed since the last frame.
The render block gets called, as long as the time spent on the frame is not already longer than the time needed to maintain the framerate specified in the $fps parameter (which defaults to 60).
If the $fps parameter was explicitly disabled (eg. with :!fps) then the render block will be called once per frame.

stop

method stop () returns Nil

Stop execution of a game, which started the last time run was called.

handle-input

method handle-input () returns Nil

Process input events and update the state of Pop::Inputs. See the documentation for Pop::Inputs.update for more details.

Calling handle-input will automatically call stop when a QUIT event is received (ie. when the game window is closed).

delta

method delta () returns Duration

Returns a Duration object representing the time elapsed since the last frame started.

wait

method wait (
    Int :$dt,
) returns Nil

Stop execution for at least the specified number of seconds.

destroy

method destroy () returns Nil

Frees any resources that have been loaded and cached by the game.

MAIN CALLBACKS

update

method update (
    &update,
) returns Nil

Set a code block to be run to update the game state on every game frame. The code will be called with the delta time in seconds as the only parameter.

The update block runs before the render block (see below), possibly multiple times per frame, depending on the values passed to run. See the entry for that method for details on the structure of the default main loop.

render

method render (
    &render,
) returns Nil

Set a code block to be run to render the game state. This block will be called up to once per frame, with no arguments.

For details on the aspects of the main loop that control whether the render block gets called or not, see the entry for the run method above.

INPUT CALLBACKS

The callbacks listed below are shortcuts for the callbacks of the same name in Pop::Inputs. For more details, see that module's documentation.

key-pressed

method key-pressed ( &cb ) returns Nil

key-released

method key-released ( &cb ) returns Nil

mouse-moved

method mouse-moved ( &cb ) returns Nil

wheel-moved

method wheel-moved ( &cb ) returns Nil

mouse-pressed

method mouse-pressed ( &cb ) returns Nil

mouse-released

method mouse-released ( &cb ) returns Nil

controller-moved

method controller-moved ( &cb ) returns Nil

controller-pressed

method controller-pressed ( &cb ) returns Nil

controller-released

method controller-released ( &cb ) returns Nil

file-dropped

method file-dropped ( &cb ) returns Nil

text-dropped

method text-dropped ( &cb ) returns Nil

text-input

method text-input ( &cb ) returns Nil

text-edited

method text-edited ( &cb ) returns Nil

WINDOW CALLBACKS

The callbacks listed below are shortcuts for the callbacks of the same name in Pop::Inputs. For more details, see that module's documentation.

focused

method focused ( &cb ) returns Nil

mouse-focused

method mouse-focused ( &cb ) returns Nil

window-exposed

method window-exposed ( &cb ) returns Nil

window-moved

method window-moved ( &cb ) returns Nil

window-resized

method window-resized ( &cb ) returns Nil

window-visible

method window-visible ( &cb ) returns Nil

ACKNOWLEDGEMENTS

The core ECS logic in Pop::Entities has been heavily influenced, both in its interface and its implementation, by EnTT.

Some of the slicing of the singleton classes is based on that seen in popular game development frameworks, but were most directly influenced by LÖVE2D.

The singleton role used in this distribution is also a greatly simplified version of Staticish, while the code in Pop::Point derives from a modified version of Point.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.