CPEngine
CosPlay game engine.
Game engine is used mostly for game lifecycle like starting and stopping as well as debugging, logging, and managing global utility and miscellaneous features.
CosPlay games follow relatively straightforward game organization:
- Initialize game engine by calling CPEngine.init or CPEngine.initEff method.
- Start the game loop by calling CPEngine.startGame or CPEngine.startGameEff method.
- Dispose the game engine calling CPEngine.dispose or CPEngine.disposeEff method.
Note that these methods have two versions:
- One that throws CPException exception in case of any errors for the classic exception-based error handling.
- Another with
Effsuffix in the name that returns scala.util.Try-monad allowing for composable effect-based error handling.
You can use either approach but you can't mix them up. Effect-based approach, however, forces a more rigorous error handling requiring to handle errors at each call.
CosPlay game organization using classic exception-based error handling:
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)
Here's the same game structure using effect-based error handling (calling sys.exit() with an appropriate exit code at each step):
import org.cosplay.*
object Game:
def main(args: Array[String]): Unit =
// Initialize the engine.
CPEngine.initEff(
CPGameInfo(name = "My Game"),
System.console() == null || args.contains("emuterm")
).recover(_ => sys.exit(1)).get
// Create game scenes & their scene objects.
val sc1 = new CPScene(...)
val sc2 = new CPScene(...)
// Start the game & wait for exit.
CPEngine.startGameEff(sc1, sc2).recover(_ => sys.exit(2)).get
// Dispose game engine.
CPEngine.disposeEff().fold(_ => sys.exit(3), _ => 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/CPEngine.initEff 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. Note also that scene and scene objects can be added, removed or modified later throughout the game lifecycle.
- Once you have all initially required scenes constructed - you can start the game by calling one of the CPEngine.startGame/CPEngine.startGameEff methods.
- Make sure to call CPEngine.dispose/CPEngine.disposeEff method upon exit from CPEngine.startGame/CPEngine.startGameEff method.
Extensions and Shortcuts
Throughout the CosPlay code, exampled and built-in games there are several extensions and syntactic shortcuts used to simplify frequently used code idioms:
| Shortcut | Replaced By |
|---|---|
x.? |
Option(x) |
x.seq |
Seq(x) |
val x = nil[Int] |
val x: List[Int] = Nil |
val x = none[Int] |
val x: Option[Int] = None |
These extensions are introduced in the global scope and can be used by any code that is using CosPlay.
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/CPEngine.initEff is called:
| System Property | Value Type | Description |
|---|---|---|
COSPLAY_GAME_ID |
String |
Internal unique game ID. |
COSPLAY_EMUTERM_FONT_NAME |
String |
Applies to the built-in terminal emulator only. Specifies the font name to use. |
COSPLAY_EMUTERM_FONT_SIZE |
Int |
Applies to the built-in terminal emulator only. Specifies the font size to use. |
COSPLAY_EMUTERM_CH_WIDTH_OFFSET |
Int |
Applies to the built-in terminal emulator only. Specifies character width offset. Can be positive or negative. Default is zero. |
COSPLAY_EMUTERM_CH_HEIGHT_OFFSET |
Int |
Applies to the built-in terminal emulator only. Specifies character height offset. Can be positive or negative. Default is zero. |
COSPLAY_EMUTERM_ANTIALIAS |
Applies 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_COLOR |
Boolean |
Forces 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_CLASSNAME |
String |
Fully 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 (see CPEngine.enableCtrlFps method)
- 'CTRL+L' - opens GUI-based loc viewer & debugger (see CPEngine.enableCtrlLog method)
- 'F12' - saves current frame screenshot as *.xp image to the current working folder.
Attributes
- Note
-
See developer guide at https://cosplayengine.com
- Example
-
See all examples under
org.cosplay.examplespackage. Each example has a complete demonstration of working with game engine including initialization and game start. - Source
- CPEngine.scala
- Graph
-
- Supertypes
-
class Objecttrait Matchableclass Any
- Self type
-
CPEngine.type