Crate piston

A modular game engine written in Rust.

This is the core library of the Piston Game engine. The Piston core library reexports the core modules.

If you are looking for a convenient window wrapper, see piston_window.

For examples, see piston-examples.

For more information and an overview, see Piston’s README in the core repository.

Design

The Piston core is a thin and modular abstraction for user input, window and event loop. This functionality is separated into 3 core modules.

The core modules are intended to be used directly by generic libraries. By depending directly on core modules, it is easier to maintain the ecosystem.

This library is intended to be used in application code. When you write application code, it is common to separate reusable code, which depends on various abstractions, from platform specific code. The reusable code that you write for applications might use the Piston core.

The default programming pattern in Piston is Model-View-Controller:

• A controller handles events and manipulates a model
• A view renders a model on the screen

For more information about this pattern, see Model-View-Controller (Wikipedia).

The most important traits in Piston are the following:

• GenericEvent (allows handling of events for controllers)
• Window (allows polling of events)

Link to documentation for core modules

• pistoncore-input (User input and event handling)
• pistoncore-window (Window abstraction)
• pistoncore-event_loop (Event loop)

Points vs Pixels

Since some computer screens have higher resolution than others, it is convenient to use two kinds of coordinate systems:

• A pixel is a single square on the screen
• A point is a unit used by window events and 2D graphics

For example, the mouse cursor position events are measured in points.

It is common to use points for 2D graphics to match window coordinates.

Unintentional blurring, e.g. of rendered text, might be a side effect incorrect sampling.

About Piston as a Game Engine

Piston is a modular game engine with a minimal core abstraction. The core connects input events, window and event loop.

Piston is designed for optimal modularity, making it optional to even use the core modules in many cases. The goal is to have as little abstraction as possible, while making larger libraries as independent as possible. The motivation is to encourage diversity and experimentation with various abstractions, without getting tied up to a fixed set of platforms, abstractions or vendors. You can combine Piston with any other library in Rust’s ecosystem. This design has worked very well so far.

For example (a few libraries, there are many more):

• Image library is standalone from both the core and the 2D graphics library, only connected through the 2D graphics backends.
• Piston’s 2D graphics is optional and can be used without a window backend. The window backend can be used without a 2D graphics backend, and so on.
• For image processing, see Imageproc.
• Dyon is a Rusty dynamically typed scripting language, using a lifetime checker without garbage collection.

For more information and an overview, see Piston’s README in the core repository.

When writing a library, please depend directly on the core module needed. This makes it less likely that the library will break.

When writing an application, it is acceptable to use the Piston core. To use it you usually need a window backend:

• pistoncore-glutin_window
• pistoncore-sdl2_window
• pistoncore-glfw_window

There are a few other window backends as well.

Plus a 2D graphics backend (optional):

• piston2d-opengl_graphics
• piston2d-gfx_graphics
• piston2d-glium_graphics

There are a few other graphics backends as well.

You will find examples of how to get started in each 2D graphics backend repository.

About Piston as a Project

The Piston project is a huge collaboration across many projects, mainly focused on maintenance of libraries and research. Since this has been going on since 2014, there is too much out there to summarize here, but roughly the project is organized into two open source organizations:

• PistonDevelopers - everything game engine related
• AdvancedResearch - everything advanced math related

In addition, we collaborate across organizations with other projects, mainly:

• Gfx-rs - everything 3D graphics related
• RustAudio - everything audio related

In addition, there are many other projects and organizations.

For more information and an overview, see Piston’s README in the core repository.

Re-exports

• pub use event_loop;
• pub use input;
• pub use window;

Modules

• controller
  Back-end agnostic controller events.
• event_id
  Event identifiers.
• generic_event
  Trait for generic events
• keyboard
  Back-end agnostic keyboard keys.
• mouse
  Back-end agnostic mouse buttons.

Structs

• AfterRenderArgs
  After render arguments.
• Api
  Stores graphics API version.
• ButtonArgs
  Button arguments.
• CloseArgs
  Close arguments.
• ControllerAxisArgs
  Components of a controller axis move event. Not guaranteed consistent across backends.
• ControllerButton
  Components of a controller button event. Not guaranteed consistent across backends.
• ControllerHat
  Components of a controller hat move event (d-Pad).
• EventSettings
  Stores event loop settings.
• Events
  An event loop iterator
• IdleArgs
  Idle arguments, such as expected idle time in seconds.
• NoWindow
  A window without user interface, often used in server event loops.
• Position
  Structure to store the window position.
• RenderArgs
  Render arguments.
• ResizeArgs
  Resize arguments.
• Size
  Structure to store the window size.
• TouchArgs
  Touch arguments
• UnsupportedGraphicsApiError
  An error for when a graphics API is unsupported.
• UpdateArgs
  Update arguments, such as delta time in seconds.
• WindowSettings
  Settings structure for window behavior.

Enums

• Button
  Models different kinds of buttons.
• ButtonState
  Stores button state.
• Event
  Models all events.
• FileDrag
  Models dragging and dropping files.
• HatState
  Stores controller hat state.
• Input
  Models input events.
• Key
  Represent a keyboard key. Keycodes follows SDL http://wiki.libsdl.org/SDLKeycodeLookup
• Loop
  Models loop events.
• Motion
  Models different kinds of motion.
• MouseButton
  Represent a mouse button.
• Touch
  Stores the touch state.

Constants

• DEFAULT_MAX_FPS
  The default maximum frames per second.
• DEFAULT_UPS
  The default updates per second.
• DEFAULT_UPS_RESET
  The default delayed updates reset.

Traits

• AdvancedWindow
  Trait representing a window with the most features that are still generic.
• AfterRenderEvent
  After rendering and buffers are swapped.
• BuildFromWindowSettings
  Constructs a window from a WindowSettings object.
• ButtonEvent
  Changed button state.
• CloseEvent
  Window is closing.
• ControllerAxisEvent
  The position of a controller axis changed.
• CursorEvent
  When window gets or loses cursor.
• EventLoop
  Methods implemented for changing event loop settings.
• FocusEvent
  When window gets or loses focus.
• GenericEvent
  Implemented by all events.
• IdleEvent
  When background tasks should be performed.
• MouseCursorEvent
  The position of the mouse cursor.
• MouseRelativeEvent
  The relative movement of mouse cursor.
• MouseScrollEvent
  The scroll of the mouse wheel.
• OpenGLWindow
  Trait for OpenGL specific operations on a window.
• PressEvent
  The press of a button.
• ReleaseEvent
  The release of a button.
• RenderEvent
  When the next frame should be rendered.
• ResizeEvent
  When the window is resized.
• TextEvent
  When receiving text from user, such as typing a character.
• TouchEvent
  When a touch is started, moved, ended or cancelled.
• UpdateEvent
  When the application state should be updated.
• Window
  Trait representing the minimum requirements for defining a window.

Type Aliases

• ProcAddress
  The type of an OpenGL function address.
• TimeStamp
  The type of time stamp.