►Pyret
▼3 Builtins and Libraries
3.1 Global Utilities
3.2 Numbers
3.3 Strings
3.4 Booleans
3.5 Raw  Array
3.6 Tables
3.7 lists
3.8 sets
3.9 arrays
3.10 string-dict
3.11 option
3.12 pick
3.13 either
3.14 srcloc
3.15 pprint
3.16 s-exp
3.17 s-exp-structs
3.18 color
3.19 image-structs
3.20 The image libraries
3.21 world
3.22 gdrive-sheets
3.23 data-source
3.24 reactors
3.25 chart
3.26 plot
3.27 statistics
3.28 math
►3.21 world
On this page:
3.21.1 Starting a big-bang
big-bang
3.21.2 Functions
on-tick
on-tick-n
to-draw
on-key
on-mouse
stop-when
is-world-config
is-key-equal
3.21.3 Data Types
World  Config
    contents    up   

3.21 world

Usage:
include world
import world as ...
Pyret’s world and reactors modules both facilitate creating animated time-based simulation and interactive programs. Using the world module and the big-bang function is the quickest way to get a basic simulation or game running. reactors provide more advanced features for exploring, testing and debugging reactive programs.

Handler functions written for big-bang are compatible with reactors, so it is easy to start with big-bang and move to reactors if you need their advanced features.

The world/reactor model is based on the universe teachpack in HtDP. You can find documentation for the teachpack here:

http://docs.racket-lang.org/teachpack/2htdpuniverse.html

3.21.1 Starting a big-bang

big-bang :: (
init :: a,
handlers :: List<WorldConfig<a>>
)
-> a

big-bang is called with an init state and a list of handler functions. It immediately creates an interactive window based on init and optionally begins drawing graphics and text as defined by the to-draw function, running handler functions scheduled by on-tick and on-tick-n as well as those triggered by on-mouse and on-key.

big-bang(init,

  [list:

    on-tick(‹expr›),

    on-tick-n(‹expr›),

    on-mouse(‹expr›),

    on-key(‹expr›),

    to-draw(‹expr›),

    stop-when(‹expr›)

  ]

)

All of the handlers for big-bang (in the list argument) are optional. They can also appear in any order — the order displayed above is not required. Each option can only appear once. So, for example, these are valid big-bangs:

include world
big-bang('inert', [list: ])

fun increment(x):
  x + 1
end

big-bang(10, [list: on-tick(increment)])
big-bang(10, [list: on-tick-n(increment, 3)])

These are not allowed:

big-bang(10, 11)
big-bang([list: on-tick(increment)])
big-bang(10, [list: not-a-handler(increment)])
big-bang(10, on-tick(increment))
3.21.2 Functions

on-tick :: (
handler :: (a -> a)
)
-> WorldConfig<a>

Consumes a function and returns a handler that, when passed to big-bang, will be called each program tick with the current world state.

on-tick-n :: (
handler :: (a -> a),
n :: Number
)
-> WorldConfig<a>

Consumes a function and returns a handler that, when passed to big-bang, will be called every n program ticks with the current world state.

to-draw :: (
drawer :: (a -> Scene)
)
-> WorldConfig<a>

Consumes a function and returns a handler that, when passed to big-bang, will inform the world program what to draw.

on-key :: (
onKey :: (a, String -> a)
)
-> WorldConfig<a>

Consumes a function and returns a handler that, when passed to big-bang, will be called every time a key is pressed. The function is called with the current world state and a String representing the pressed key. For most keys, this is just the corresponding single character.

The special keys are:

  • Backspace key: "backspace"

  • Tab key: "tab"

  • Enter key: "enter"

  • Shift key: "shift"

  • Control key: "control"

  • Pause key: "pause"

  • Escape key: "escape"

  • Prior key: "prior"

  • Next key: "next"

  • End key: "end"

  • Home key: "home"

  • Left arrow: "left"

  • Up arrow: "up"

  • Right arrow: "right"

  • Down arrow: "down"

  • Print key: "print"

  • Insert key: "insert"

  • Delete key: "delete"

  • Backspace key: "backspace"

  • Num lock key: "numlock"

  • Scroll key: "scroll"

on-mouse :: (
mouse-handler :: (a, Number, Number, String -> a)
)
-> WorldConfig<a>

Consumes a function and returns a handler that, when passed to big-bang, will be called on every sampled mouse movement. The function will receive the world state, the current x and y positions of the mouse, and a String representing a mouse event. Possible mouse events are:

  • "button-down" signals that the computer user has pushed a mouse button down;

  • "button-up" signals that the computer user has let go of a mouse button;

  • "drag" signals that the computer user is dragging the mouse. A dragging event occurs when the mouse moves while a mouse button is pressed.

  • "move" signals that the computer user has moved the mouse;

  • "enter" signals that the computer user has moved the mouse into the canvas area; and

  • "leave" signals that the computer user has moved the mouse out of the canvas area.

stop-when :: (
stopper :: (a -> Boolean)
)
-> WorldConfig<a>

Consumes a function and returns a handler that, when passed to big-bang, will be called to determine if the world should stop running. If the function returns true, then no other handlers will be called. The big-bang function will return this last world state.

is-world-config :: (
v :: Any
)
-> WorldConfig<a>

Tests if the input is of type WorldConfig.

is-key-equal :: (
key1 :: String,
key2 :: String
)
-> WorldConfig<a>

Tests if two key events are equals to each other.

3.21.3 Data Types

WorldConfig<a>
This type includes the values that can be passed to big-bang as event handlers (e.g. on-tick and on-key), renderers (e.g. to-draw), and other configuration options (e.g. stop-when).

    contents    up