public abstract class CellGame
extends java.lang.Object
A CellGame is a game made with Cell2D. A certain number of times per second, a CellGame executes a frame, in which it processes input, updates the logic of the game, and renders visuals.
A CellGame has one or more GameStates, each with a non-negative integer ID that is unique within the CellGame. A CellGame is in exactly one of these GameStates at any given time, and can transition between them. Each GameState has its own actions to take every frame and in response to specific events, but it only takes these actions while the CellGame is in it. If a GameState is created with an ID that another GameState of the same CellGame already has, the old GameState can no longer be entered.
A CellGame renders visuals on a rectangular grid of pixels called its screen. Points on the screen have x-coordinates that increase from left to right, as well as y-coordinates that increase from top to bottom. The dimensions of the screen are not necessarily the same as the dimensions of the CellGame's program window, as the screen may be scaled to different apparent sizes using the CellGame's scale factor. A CellGame may be displayed in windowed or fullscreen mode.
While a CellGame is rendering visuals, the region of the Graphics context to which it is rendering that is outside its screen cannot be drawn to. When drawn to the Graphics context, shapes and Drawables will automatically be clipped so that they do not extend beyond the screen.
A CellGame processes input in the form of a fixed number of binary commands, numbered from 0 to getNumCommands() - 1 inclusive, as well as the position of the mouse cursor on the screen and the movement of the mouse wheel. Controls, which represent keys, controller buttons, etc. may be bound to at most one command at a time so that when they are pressed, held, and released, so too are the commands to which they are bound. If an attempt is made to bind a Control that is already bound, it will be unbound from its current command first. A CellGame considers Controls to be the same Control if they are equal - that is, if they represent the same input. A CellGame also allows for the temporary processing of input as assignments of Controls to specific commands, or as the typing of text to a specific String.
A CellGame also controls the playing and stopping of Music tracks. It contains a data structure called a music stack in which different integer priority values may be assigned one or more Music tracks each. Only the Music tracks assigned to the greatest priority in the stack will play at any given time. If a currently playing Music track finishes, it will automatically be removed from the top of the music stack.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
VERSION
The version number of Cell2D, currently 2.1.1.
|
Constructor and Description |
---|
CellGame(java.lang.String title,
int numCommands,
int fps,
int screenWidth,
int screenHeight,
double scaleFactor,
boolean fullscreen,
java.lang.String iconPath)
Constructs a CellGame.
|
Modifier and Type | Method and Description |
---|---|
void |
addMusic(int priority,
Music music,
boolean loop)
Adds the specified Music track to the specified priority in this
CellGame's music stack, replacing and removing all other Music tracks
assigned to that priority.
|
void |
addMusic(int priority,
Music music,
boolean loop,
boolean replace)
Adds the specified Music track to the specified priority in this
CellGame's music stack.
|
void |
addMusic(int priority,
Music music,
double speed,
double volume,
boolean loop)
Adds the specified Music track to the specified priority in this
CellGame's music stack, replacing and removing all other Music tracks
assigned to that priority.
|
void |
addMusic(int priority,
Music music,
double speed,
double volume,
boolean loop,
boolean replace)
Adds the specified Music track to the specified priority in this
CellGame's music stack.
|
void |
addMusic(Music music,
boolean loop)
Adds the specified Music track to the greatest priority in this
CellGame's music stack, replacing and removing all other Music tracks
assigned to that priority, or to priority 0 if the music stack is empty.
|
void |
addMusic(Music music,
boolean loop,
boolean replace)
Adds the specified Music track to the greatest priority in this
CellGame's music stack, or to priority 0 if the music stack is empty.
|
void |
addMusic(Music music,
double speed,
double volume,
boolean loop)
Adds the specified Music track to the greatest priority in this
CellGame's music stack, replacing and removing all other Music tracks
assigned to that priority, or to priority 0 if the music stack is empty.
|
void |
addMusic(Music music,
double speed,
double volume,
boolean loop,
boolean replace)
Adds the specified Music track to the greatest priority in this
CellGame's music stack, or to priority 0 if the music stack is empty.
|
void |
beginTypingString(int maxLength)
Instructs this CellGame to interpret all inputs as typing a String with a
specified maximum length until further notice.
|
void |
beginTypingString(java.lang.String initialString,
int maxLength)
Instructs this CellGame to interpret all inputs as typing a String with a
specified initial value and maximum length until further notice.
|
void |
bindControl(int commandNum,
Control control)
Binds the specified Control to the specified command.
|
void |
cancelBindToCommand()
Cancels this CellGame's instruction to bind the next valid Control
pressed to a specified command, if it has been instructed to do so.
|
void |
cancelTypingString()
Instructs this CellGame to stop interpreting inputs as typing a String,
if it was doing so, and consider the typing canceled.
|
void |
clearControls(int commandNum)
Unbinds all of the specified command's Controls from it.
|
void |
clearMusic()
Removes from this CellGame's music stack all Music tracks assigned to any
priority, leaving the stack empty.
|
void |
close()
Instructs this CellGame to close itself the next time it finishes a game
logic update.
|
boolean |
commandHeld(int commandNum)
Returns whether the specified command is being held this frame.
|
boolean |
commandPressed(int commandNum)
Returns whether the specified command was pressed this frame.
|
boolean |
commandReleased(int commandNum)
Returns whether the specified command was released this frame.
|
void |
enterState(int id)
Instructs this CellGame to enter its GameState with the specified ID the
next time it finishes a game logic update.
|
void |
enterState(int id,
Color fadeColor,
int fadeOutTime,
int fadeInTime)
Instructs this CellGame to enter its GameState with the specified ID the
next time it finishes a game logic update, using a visual
fade-out/fade-in effect to transition to it from the current GameState.
|
int |
getBindingCommandNum()
Returns the number of the command to which this CellGame has been
instructed to bind the next valid Control pressed, or -1 if there is
none.
|
java.util.Set<Control> |
getControlsFor(int commandNum)
Returns an unmodifiable Set view of all of the Controls that are bound to
the specified command.
|
GameState |
getCurrentState()
Returns the GameState that this CellGame is currently in.
|
int |
getFPS()
Returns the number of frames that this CellGame executes per second.
|
java.lang.String |
getIconPath()
Returns the relative path to the image file that this CellGame's program
window uses as its icon, or null if the window uses the default LWJGL 2
icon.
|
int |
getMaxTypingStringLength()
Returns the maximum length in characters of the String that this CellGame
is being used to type, or 0 if this CellGame is not being used to type a
String.
|
int |
getMouseWheelChange()
Returns the change in the position of the mouse wheel since last frame.
|
int |
getMouseX()
Returns the x-coordinate in pixels of the mouse cursor on this CellGame's
screen.
|
int |
getMouseY()
Returns the y-coordinate in pixels of the mouse cursor on this CellGame's
screen.
|
Music |
getMusic()
Returns the Music track assigned to the greatest priority in this
CellGame's music stack, if the music stack is not empty and there is
exactly one such Music track, or null otherwise.
|
Music |
getMusic(int priority)
Returns the Music track assigned to the specified priority in this
CellGame's music stack, if there is exactly one such Music track, or null
otherwise.
|
int |
getMusicStackTop()
Returns the greatest priority in this CellGame's music stack to which any
Music tracks are assigned, or 0 if the music stack is empty.
|
java.util.Set<Music> |
getMusicTracks()
Returns an unmodifiable Set view of the Music tracks that are assigned to
the greatest priority in this CellGame's music stack, or an unmodifiable
empty Set if the music stack is empty.
|
java.util.Set<Music> |
getMusicTracks(int priority)
Returns an unmodifiable Set view of the Music tracks that are assigned to
the specified priority in this CellGame's music stack, or an unmodifiable
empty Set if the music stack is empty.
|
int |
getNumCommands()
Returns how many commands this CellGame has.
|
double |
getScaleFactor()
Returns the factor by which this CellGame's screen is scaled to make the
size of the program window.
|
int |
getScreenHeight()
Returns the height in pixels of this CellGame's screen.
|
int |
getScreenWidth()
Returns the width in pixels of this CellGame's screen.
|
GameState |
getState(int id)
Returns this CellGame's GameState with the specified ID, or null if there
is none.
|
java.lang.String |
getTypingString()
Returns the String that this CellGame is being used to type, or null if
there is none.
|
abstract void |
initActions()
Actions for this CellGame to take when initializing itself before
entering its first GameState.
|
boolean |
isFullscreen()
Returns whether this CellGame is in fullscreen mode.
|
void |
loadLoadingAssets()
Loads any assets that are used in renderLoadingVisuals().
|
static void |
loadNatives(java.lang.String path)
Loads the native libraries that are necessary for LWJGL 2, and thus
Cell2D, to run.
|
boolean |
musicIsAtPriority(int priority,
Music music)
Returns whether the specified Music track is assigned to the specified
priority in this CellGame's music stack.
|
void |
removeMusic()
Removes from the greatest priority in this CellGame's music stack all of
the Music tracks currently assigned to it, if the music stack is not
empty.
|
void |
removeMusic(int priority)
Removes from the specified priority in this CellGame's music stack all of
the Music tracks currently assigned to it.
|
void |
removeMusic(int priority,
Music music)
Removes the specified Music track from the specified priority in this
CellGame's music stack if it is currently assigned to that priority.
|
void |
removeMusic(Music music)
Removes the specified Music track from the greatest priority in this
CellGame's music stack if it is currently assigned to that priority.
|
void |
renderActions(Graphics g,
int x1,
int y1,
int x2,
int y2)
Actions for this CellGame to take each frame to render visuals after its
current GameState has finished rendering.
|
void |
renderLoadingVisuals(Graphics g,
int x1,
int y1,
int x2,
int y2)
Renders the visuals that this CellGame will display while its
initActions() are in progress.
|
void |
setFPS(int fps)
Sets the number of frames that this CellGame executes per second to the
specified value.
|
void |
setFullscreen(boolean fullscreen)
Sets whether this CellGame is in fullscreen mode.
|
void |
setScaleFactor(double scaleFactor)
Sets the factor by which this CellGame's screen is scaled to make the
size of the program window to the specified value.
|
void |
setScreenHeight(int screenHeight)
Sets the height in pixels of this CellGame's screen to the specified
value.
|
void |
setScreenWidth(int screenWidth)
Sets the width in pixels of this CellGame's screen to the specified
value.
|
static void |
startGame(CellGame game)
Starts a CellGame.
|
void |
unbindControl(Control control)
Unbinds the specified Control from its command, if it is bound to one.
|
void |
waitToBindToCommand(int commandNum)
Instructs this CellGame to bind the next valid Control pressed to the
specified command.
|
public static final java.lang.String VERSION
public CellGame(java.lang.String title, int numCommands, int fps, int screenWidth, int screenHeight, double scaleFactor, boolean fullscreen, java.lang.String iconPath)
title
- The title of this CellGame as seen on its program windownumCommands
- The total number of input commands that this CellGame
needs to keep track offps
- The number of frames that this CellGame will execute every
secondscreenWidth
- The initial width of this CellGame's screen in pixelsscreenHeight
- The initial height of this CellGame's screen in
pixelsscaleFactor
- The initial factor by which the screen should be
scaled to make the size of the program windowfullscreen
- Whether this CellGame should start in fullscreen modeiconPath
- The relative path to the image file that this CellGame's
program window should use as its icon, or null if the window should use
the default LWJGL 2 iconpublic static void loadNatives(java.lang.String path)
path
- The relative path to the folder containing the native
librariespublic static void startGame(CellGame game)
game
- The CellGame to startpublic final void close()
public final GameState getState(int id)
id
- The ID of the GameState to returnpublic final GameState getCurrentState()
public final void enterState(int id)
id
- The ID of the GameState to enterpublic final void enterState(int id, Color fadeColor, int fadeOutTime, int fadeInTime)
id
- The ID of the GameState to enterfadeColor
- The color of the fade effectfadeOutTime
- The number of frames to be spent fading out from the
current GameStatefadeInTime
- The number of frames to be spent fading in to the new
GameStatepublic void loadLoadingAssets()
public void renderLoadingVisuals(Graphics g, int x1, int y1, int x2, int y2)
g
- The Graphics context to which this CellGame is rendering the
loading visualsx1
- The x-coordinate in pixels of the screen's left edge on the
Graphics contexty1
- The y-coordinate in pixels of the screen's top edge on the
Graphics contextx2
- The x-coordinate in pixels of the screen's right edge on the
screen on the Graphics contexty2
- The y-coordinate in pixels of the screen's bottom edge on the
Graphics contextpublic abstract void initActions()
public void renderActions(Graphics g, int x1, int y1, int x2, int y2)
g
- The Graphics context to which this CellGame is rendering its
visuals this framex1
- The x-coordinate in pixels of the screen's left edge on the
Graphics contexty1
- The y-coordinate in pixels of the screen's top edge on the
Graphics contextx2
- The x-coordinate in pixels of the screen's right edge on the
screen on the Graphics contexty2
- The y-coordinate in pixels of the screen's bottom edge on the
Graphics contextpublic final int getNumCommands()
public final java.util.Set<Control> getControlsFor(int commandNum)
commandNum
- The number of the command whose controls are to be
returnedpublic final void bindControl(int commandNum, Control control)
commandNum
- The command to bind the specified Control tocontrol
- The Control to bind to the specified commandpublic final void unbindControl(Control control)
control
- The Control to be unboundpublic final void clearControls(int commandNum)
commandNum
- The number of the command whose Controls are to be
unboundpublic final int getBindingCommandNum()
public final void waitToBindToCommand(int commandNum)
commandNum
- The number of the command to which the next valid
Control pressed should be boundpublic final void cancelBindToCommand()
public final boolean commandPressed(int commandNum)
commandNum
- The number of the command to examinepublic final boolean commandHeld(int commandNum)
commandNum
- The number of the command to examinepublic final boolean commandReleased(int commandNum)
commandNum
- The number of the command to examinepublic final int getMouseX()
public final int getMouseY()
public final int getMouseWheelChange()
public final java.lang.String getTypingString()
public final int getMaxTypingStringLength()
public final void beginTypingString(int maxLength)
maxLength
- The maximum length in characters of the String to be
typedpublic final void beginTypingString(java.lang.String initialString, int maxLength)
initialString
- The initial value of the String to be typed, or null
if the String should be empty initiallymaxLength
- The maximum length in characters of the String to be
typedjava.lang.RuntimeException
- if this CellGame has already been instructed to
bind the next Control pressed to a commandpublic final void cancelTypingString()
public final int getFPS()
public final void setFPS(int fps)
fps
- The new number of frames per secondpublic final int getScreenWidth()
public final void setScreenWidth(int screenWidth)
screenWidth
- The new screen widthpublic final int getScreenHeight()
public final void setScreenHeight(int screenHeight)
screenHeight
- The new screen heightpublic final double getScaleFactor()
public final void setScaleFactor(double scaleFactor)
scaleFactor
- The new screen scale factorpublic final boolean isFullscreen()
public final void setFullscreen(boolean fullscreen)
fullscreen
- Whether this CellGame should be in fullscreen modepublic final java.lang.String getIconPath()
public final int getMusicStackTop()
public final java.util.Set<Music> getMusicTracks(int priority)
priority
- The priority of the Music tracks to returnpublic final java.util.Set<Music> getMusicTracks()
public final Music getMusic(int priority)
priority
- The priority of the Music track to returnpublic final Music getMusic()
public final boolean musicIsAtPriority(int priority, Music music)
priority
- The priority to examinemusic
- The Music track to search forpublic final void addMusic(int priority, Music music, boolean loop, boolean replace)
priority
- The priority to assign the specified Music track tomusic
- The Music track to addloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncereplace
- If true, all other Music tracks assigned to the specified
priority will be removed from itpublic final void addMusic(int priority, Music music, double speed, double volume, boolean loop, boolean replace)
priority
- The priority to assign the specified Music track tomusic
- The Music track to addspeed
- The speed at which to play the specified Music track when it
playsvolume
- The volume at which to play the specified Music track when
it playsloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncereplace
- If true, all other Music tracks assigned to the specified
priority will be removed from itpublic final void addMusic(int priority, Music music, boolean loop)
priority
- The priority to assign the specified Music track tomusic
- The Music track to addloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncepublic final void addMusic(int priority, Music music, double speed, double volume, boolean loop)
priority
- The priority to assign the specified Music track tomusic
- The Music track to addspeed
- The speed at which to play the specified Music track when it
playsvolume
- The volume at which to play the specified Music track when
it playsloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncepublic final void addMusic(Music music, boolean loop, boolean replace)
music
- The Music track to addloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncereplace
- If true, all other Music tracks assigned to the priority
to which the specified Music track is added will be removed from itpublic final void addMusic(Music music, double speed, double volume, boolean loop, boolean replace)
music
- The Music track to addspeed
- The speed at which to play the specified Music track when it
playsvolume
- The volume at which to play the specified Music track when
it playsloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncereplace
- If true, all other Music tracks assigned to the priority
to which the specified Music track is added will be removed from itpublic final void addMusic(Music music, boolean loop)
music
- The Music track to addloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncepublic final void addMusic(Music music, double speed, double volume, boolean loop)
music
- The Music track to addspeed
- The speed at which to play the specified Music track when it
playsvolume
- The volume at which to play the specified Music track when
it playsloop
- If true, the Music track will loop indefinitely until
stopped when it plays; otherwise, it will play oncepublic final void removeMusic(int priority, Music music)
priority
- The priority from which to remove the specified Music
trackmusic
- The Music track to removepublic final void removeMusic(int priority)
priority
- The priority from which to remove all Music trackspublic final void removeMusic(Music music)
music
- The Music track to removepublic final void removeMusic()
public final void clearMusic()