1. Home
  2. Key Concepts

Key Concepts

In A Glance

CosPlay is a Scala3-based game engine for developing 2D ASCII-based games. CosPlay API follows a familiar gamedev design:

  • Game engine (CPEngine) is responsible for starting a game loop.
  • A game is a collection of one or more scenes (CPScene).
  • A scene is a collection of one or more scene objects (CPSceneObject).
  • Scene object is a game element that has a state and can draw itself on the scene's canvas.
  • There are also assets like sounds, images, fonts, etc. that are used by scene objects.
  • Rendering of scene objects defines the game's visual gameplay.

Around 30 times per second (30 FPS) game engine takes the current scene and redraws all of its scene objects. During its update each scene object has access to the keyboard input, messaging, collision resolution, creating and removing scene objects and scenes, as well as many other in-game APIs.

In a nutshell - that's it. 👌

Key APIs

Although CosPlay API consists of 60+ classes, traits and objects, the list of the key types is relatively short. For the full API up-to-date documentation you should always consult the latest Scaladoc.

Here's the list of key entities in CosPlay API. Once you know these - you know 90% of CosPlay, the rest is just the details on particular methods, specialized sprites and few other odds and ends:

Key APIDescription
CPEngine

CosPlay game engine object. It allows starting and stopping games, listen for rendering statistics, add and remove external input devices, pause and resume games, open GUI log viewer, and get other game engine properties like FPS.

More on Game Engine
More on Logging & Debugging

CPPixel

A single character "pixel" is a fundamental graphics unit in native ASCII games. It represents the smallest area that can be rendered on the screen. CosPlay pixel is immutable and consists of a character from the ASCII character set, a foreground color, an optional background color and an optional tag. Note that pixel itself does not have a Z-index as it can be rendered at any Z-index.

More on Pixel & Colors

CPColor

A color is an immutable container for 24-bit RGB/HSB value. This class has constants for all X11 and "xterm" colors as well as many color manipulation utilities.

More on Pixel & Colors

CPDim

2D dimension immutable container. It contains width and height properties.

CPRect

This immutable class describes coordinate and the dimension of the rectangular shape. Note that this class only describes the rectangular shape but does not hold any content.

CPImage

Defines immutable rectangular shape and its content as a collection of CPPixel objects. Image is one of the key types in CosPlay. Almost everything that is drawn on the screen is represented by an image: FIGLet font string, animation sprites, video and animation frames, etc. Image itself is just a container for pixels. It can be created in-code or loaded and saved from and to the external file or resource.

More on Images

CPScene

Scene is a mutable container for CPSceneObject instances. Scene can be adaptive and static in terms of its dimension. Scene objects can be added or removed to and from scene at any point. Scene also has the canvas on which all of its scene objects render themselves. That canvas is then rendered on the ANSI terminal.

More on Scene & Scene Objects

CPSceneObject

Scene object and its various specific subclasses called "sprites" are the main game elements in CosPlay. Scene objects belong to a scene. Scene objects can be visible or invisible, have rectangular shape, have XY-coordinates of its left-top corner and Z-index. On each game frame each scene object from the current scene gets updated and rendered on the scene's canvas.

Note that in almost all cases the terms SceneObject and Sprite are interchangeable.

More on Scene & Scene Objects

CPFont

Immutable font descriptor. CosPlay comes with a full support for FIGLet fonts as well as standard "system" font.

More on Fonts

CPSound

Sound clip container. Sound object supports three formats: AIFF, AU or WAV. Sound object is immutable but its playback can be controlled with changing volume, balance, rate, fade in and out. Sounds are inherently asynchronous objects, you can have many sounds objects, all of them are independent of each other, and you can play them in parallel.

More on Audio