CPEngine

object CPEngine

CosPlay game engine.

Game engine is mostly an internal object, and it is only used at the beginning of the game. It provides variety of utility and miscellaneous methods for games.

Most CosPlay games follow this basic game organization:

import org.cosplay.*

object Game:
  def main(args: Array[String]): Unit =
      // Initialize the engine.
      CPEngine.init(
           CPGameInfo(name = "My Game"),
           System.console() == null || args.contains("emuterm")
      )

      // Create game scenes & their scene objects.
      val sc1 = new CPScene(...)
      val sc2 = new CPScene(...)

      // Start the game & wait for exit.
      try CPEngine.startGame(sc1, sc2)
      finally CPEngine.dispose()

      sys.exit(0)

Notes:

  • Game start in a standard Scala way. It is recommended to use main(...) function for better compatibility.
  • Create CPGameInfo object that describes the game and its properties.
  • Initialize game engine by calling CPEngine.init method passing it game descriptor and terminal emulation flag.
  • Create all necessary scenes, scene objects and assets. You can organize these objects in any desirable way - CosPlay does not impose any restrictions or limitation on how it is should be done.
  • Once you have all scenes constructed - you can start the game by calling one of the CPEngine.startGame methods.
  • Make sure to call CPEngine.dispose method upon exit from CPEngine.startGame method.

System Properties

CosPlay game engine supports the following system properties that control various aspects of its operation. Note that these properties must be set before method CPEngine.init is called:

System PropertyValue TypeDescription
COSPLAY_EMUTERM_FONT_NAMEStringApplies to the built-in terminal emulator only. Specifies the font name to use.
COSPLAY_EMUTERM_FONT_SIZEIntApplies to the built-in terminal emulator only. Specifies the font size to use.
COSPLAY_EMUTERM_CH_WIDTH_OFFSETIntApplies to the built-in terminal emulator only. Specifies character width offset. Can be positive or negative. Default is zero.
COSPLAY_EMUTERM_CH_HEIGHT_OFFSETIntApplies to the built-in terminal emulator only. Specifies character height offset. Can be positive or negative. Default is zero.
COSPLAY_EMUTERM_ANTIALIASApplies to the built-in terminal emulator only. If system property is present - the font rendering will use antialiasing. By default, no antialiasing is used.
COSPLAY_FORCE_8BIT_COLORBooleanForces the automatic conversion from 24-bit color to 8-bit color. Only needed when running in the native terminal that does not support 24-bit color. Default value is false.
COSPLAY_TERM_CLASSNAMEStringFully qualified class name for the custom terminal emulator implementation. Class must implement org.cosplay.CPTerminal trait.

Reserved Keyboard Keys

There are three reserved key strokes that are used by the game engine itself and therefore NOT available to the game. These keystrokes are intercepted before frame update and not propagated to the scene object context:

  • 'CTRL+Q' - toggles in-game FPS overlay
  • 'CTRL+L' - opens GUI-based loc viewer & debugger
  • 'F12' - saves current frame screenshot as *.xp image to the current working folder.
Note:

See developer guide at https://cosplayengine.com

Example:

See all examples under org.cosplay.examples package. Each example has a complete demonstration of working with game engine including initialization and game start.

Source:
CPEngine.scala
class Object
trait Matchable
class Any

Type members

Classlikes

Value members

Concrete methods

def addInput(in: CPInput): Unit

Adds external input devices.

Adds external input devices.

Value parameters:
in

External input device to add.

Source:
CPEngine.scala

Adds the rendering stats listener.

Adds the rendering stats listener.

Value parameters:
f

Listener to add.

Source:
CPEngine.scala
def debugStep(kbKey: Option[CPKeyboardKey]): Unit

Debug steps through the game on frame at a time. Note that the game must be paused. Engine must be initialized before this call otherwise exception is thrown.

Debug steps through the game on frame at a time. Note that the game must be paused. Engine must be initialized before this call otherwise exception is thrown.

Value parameters:
kbKey

Optional keyboard key event to emulate for this debug step. If provided, the real keyboard event, if any, will be ignored.

Source:
CPEngine.scala
def dispose(): Unit

Disposes the game engine. This method must be called upon exit from the startGame method. Engine must be initialized before this call otherwise exception is thrown.

Disposes the game engine. This method must be called upon exit from the startGame method. Engine must be initialized before this call otherwise exception is thrown.

Source:
CPEngine.scala
def exitGame(): Unit

Exits the game. Calling this method will exit the startGame method. Engine must be initialized before this call otherwise exception is thrown.

Exits the game. Calling this method will exit the startGame method. Engine must be initialized before this call otherwise exception is thrown.

Source:
CPEngine.scala

Gets the game information supplied to init method.

Gets the game information supplied to init method.

Source:
CPEngine.scala

Gets current rendering statistics, if available.

Gets current rendering statistics, if available.

See also:
Source:
CPEngine.scala
def init(gameInfo: CPGameInfo, emuTerm: Boolean): Unit

Initializes the game engine.

Initializes the game engine.

Value parameters:
emuTerm

Whether or not to use built-in terminal emulator. If not provided, the default value will be result of this expression:

System.console() == null
gameInfo

Game information.

Source:
CPEngine.scala
def isGamePaused: Boolean

Tests whether or not the game is paused. Engine must be initialized before this call otherwise exception is thrown.

Tests whether or not the game is paused. Engine must be initialized before this call otherwise exception is thrown.

Source:
CPEngine.scala
def isInit: Boolean

Tests whether or not game engine is initialized.

Tests whether or not game engine is initialized.

Source:
CPEngine.scala
def openLog(): Unit

Opens GUI-based log window by bringing it upfront. Can also be open by pressing Ctrl-l in the game. Engine must be initialized before this call otherwise exception is thrown.

Opens GUI-based log window by bringing it upfront. Can also be open by pressing Ctrl-l in the game. Engine must be initialized before this call otherwise exception is thrown.

Source:
CPEngine.scala
def pauseGame(): Unit

Pauses the game. Engine must be initialized before this call otherwise exception is thrown.

Pauses the game. Engine must be initialized before this call otherwise exception is thrown.

Source:
CPEngine.scala
def removeInput(in: CPInput): Unit

Removes external input devices.

Removes external input devices.

Value parameters:
in

External input device to remove.

Source:
CPEngine.scala

Removes the rendering stats listener.

Removes the rendering stats listener.

Value parameters:
f

Listener to remove.

Source:
CPEngine.scala
def resumeGame(): Unit

Resumes the game. Engine must be initialized before this call otherwise exception is thrown.

Resumes the game. Engine must be initialized before this call otherwise exception is thrown.

Source:
CPEngine.scala
def rootLog(): CPLog

Gets root log for the game engine.

Gets root log for the game engine.

NOTE: unlike most other methods in the game engine, you can use this method before engine is initialized. In such case the log entries will be buffered until the engine is initialized.

Source:
CPEngine.scala
def showFpsOverlay(show: Boolean): Unit

Shows or hides the built-in FPS overlay in the right top corner. Can also be turned on or off by pressing Ctrl-q in the game. Engine must be initialized before this call otherwise exception is thrown.

Shows or hides the built-in FPS overlay in the right top corner. Can also be turned on or off by pressing Ctrl-q in the game. Engine must be initialized before this call otherwise exception is thrown.

Value parameters:
show

Show/hide flag.

Source:
CPEngine.scala
def startDebug(): Unit

Shortcut for the following two calls:

Shortcut for the following two calls:

   pauseGame()
   openLog()

This is a convenient call to programmatically start the debugging session. Engine must be initialized before this call otherwise exception is thrown.

Source:
CPEngine.scala
def startGame(startSceneId: String, scs: CPScene*): Unit

Starts the game. Engine must be initialized before this call otherwise exception is thrown.

Starts the game. Engine must be initialized before this call otherwise exception is thrown.

Value parameters:
scs

Set of scene comprising the game. Note that scenes can be dynamically added or removed.

startSceneId

ID of the scene to start with.

Source:
CPEngine.scala
def startGame(startSceneId: String, scs: List[CPScene]): Unit

Starts the game. Engine must be initialized before this call otherwise exception is thrown.

Starts the game. Engine must be initialized before this call otherwise exception is thrown.

Value parameters:
scs

Set of scene comprising the game. Note that scenes can be dynamically added or removed.

startSceneId

ID of the scene to start with.

Source:
CPEngine.scala
def startGame(scenes: CPScene*): Unit

Starts the game. Games start with the first scene in the list. Engine must be initialized before this call otherwise exception is thrown.

Starts the game. Games start with the first scene in the list. Engine must be initialized before this call otherwise exception is thrown.

Value parameters:
scenes

Set of scene comprising the game. Note that scenes can be dynamically added or removed.

Source:
CPEngine.scala
def startGame(scenes: List[CPScene]): Unit

Starts the game. Games start with the first scene in the list. Engine must be initialized before this call otherwise exception is thrown.

Starts the game. Games start with the first scene in the list. Engine must be initialized before this call otherwise exception is thrown.

Value parameters:
scenes

Set of scene comprising the game. Note that scenes can be dynamically added or removed.

Source:
CPEngine.scala

Concrete fields

val fps: Int

Target FPS of the game engine. If the actual frame rate exceeds this value the game engine will throttle the execution and release spare cycle to the user logic. Default value is 30.

Target FPS of the game engine. If the actual frame rate exceeds this value the game engine will throttle the execution and release spare cycle to the user logic. Default value is 30.

Source:
CPEngine.scala
val frameMicros: Long

Microseconds per frame assuming target FPS.

Microseconds per frame assuming target FPS.

Source:
CPEngine.scala
val frameMillis: Long

Milliseconds per frame assuming target FPS.

Milliseconds per frame assuming target FPS.

Source:
CPEngine.scala
val frameNanos: Long

Nanoseconds per frame assuming target FPS.

Nanoseconds per frame assuming target FPS.

Source:
CPEngine.scala