CPTerminal

Output terminal interface.

This is game engine view on the underlying terminal. CosPlay comes built-in with two implementations for this interface:

  • org.cosplay.impl.jlineterm.CPJLineTerminal native JLine-based implementation that works with any OS command line terminal application supporting ANSI escape sequences are a standard for in-band signaling to control cursor location, color, font styling, and other options. For running games in xterm, iTerm, any VTE-based terminal, Windows Terminal, etc. this is the implementation to use.
  • org.cosplay.impl.emuterm.CPEmuTerminal GUI-based terminal emulator. It behaves in exactly the same manner as native ANSI-based terminal. It takes no advantage of raster graphics in drawing or color rendering. It also adheres to the FPS capping by the game engine. Terminal emulator is an ideal tool during the game development as you can quickly iterate, start and stop games right from IDEs without any need for the external builds.

When initializing CosPlay game engine using one of the CPEngine.init methods you are passing a boolean parameter which indicates whether to use native or a GUI-based terminal emulator. This way the game engine automatically knows which of the two built-in implementations to use and you don't need to specify these classes anywhere else. For the most use cases this is all that is needed.

Note that there's an easy way to check whether or not your game is running in the native terminal. Execute the following code somewhere in your game engine initialization routine:

   val isInNativeTerm = System.console() != null

and pass the appropriate flag into one of the CPEngine.init methods. This way your game will automatically choose the appropriate terminal implementation based on what environment it is running on.

Custom Terminal Implementation

You may decide to provide your own terminal implementation, for example, targeting iOS, Android or WebGL output. Here are the steps to do it:

  • Create a class that implements this trait.
  • This class should have at least one public constructor that takes one parameter of type CPGameInfo.
  • This class should be instantiable through standard reflection from Scala code.
  • Set system property COSPLAY_TERM_CLASSNAME=x.y.z.MyTerm, where x.y.z.MyTerm is a fully qualified name of the class you developed. Make sure to set this system property before calling one of the CPEngine.init methods.
  • Initialize the game engine as usual. Setting COSPLAY_TERM_CLASSNAME system property will override the default terminal selection.
See also:

org.cosplay.impl.jlineterm.CPJLineTerminal

org.cosplay.impl.emuterm.CPEmuTerminal

Source:
CPTerminal.scala
class Object
trait Matchable
class Any

Value members

Abstract methods

def dispose(): Unit

Disposes this terminal. Terminal cannot be accessed after this call.

Disposes this terminal. Terminal cannot be accessed after this call.

Source:
CPTerminal.scala

Gets current terminal dimension.

Gets current terminal dimension.

Source:
CPTerminal.scala

Gets a root logger for this terminal.

Gets a root logger for this terminal.

Source:
CPTerminal.scala
def isNative: Boolean

Tests whether or not this implementation deals with a native ANSI-based terminal. GUI-based terminal emulator implementation returns false, while JLine-based built-in implementation returns true.

Tests whether or not this implementation deals with a native ANSI-based terminal. GUI-based terminal emulator implementation returns false, while JLine-based built-in implementation returns true.

Source:
CPTerminal.scala
def kbRead(): Option[CPKeyboardKey]

This is called if isNative method returns false. This call should return a pressed keyboard key.

This is called if isNative method returns false. This call should return a pressed keyboard key.

See also:
Source:
CPTerminal.scala
def nativeKbRead(timeoutMs: Long): Int

This is called if isNative method returns true. This call should return a pressed ASCII keyboard key. Method should return -1 if given timeout elapsed and no terminal key press detected.

This is called if isNative method returns true. This call should return a pressed ASCII keyboard key. Method should return -1 if given timeout elapsed and no terminal key press detected.

Value parameters:
timeoutMs

Timeout in milliseconds waiting for the terminal key press.

Source:
CPTerminal.scala
def render(scr: CPScreen, camRect: CPRect, forceRedraw: Boolean): Unit

Renders given screen. Note that both screen and camera frame can be smaller, equal or bigger than available terminal dimension.

Renders given screen. Note that both screen and camera frame can be smaller, equal or bigger than available terminal dimension.

Value parameters:
camRect

Sub-region of screen to draw, i.e. camera frame. Camera frame is always smaller or equal to the screen dimension.

forceRedraw

Whether or not to force a full redraw.

scr

Entire scene screen.

Source:
CPTerminal.scala
def setTitle(s: String): Unit

Sets the title of the terminal. Implementation can ignore this call if this is not supported by the underlying terminal application.

Sets the title of the terminal. Implementation can ignore this call if this is not supported by the underlying terminal application.

Value parameters:
s

Terminal title to set.

Source:
CPTerminal.scala