The java GameBox class

[zingbat]

I have a project proposition. A gamebox is an idea i had similar to a java sandbox for games. It works on top of any opengl

java api and isolates a game creator from the java platform complexities and multiple OS peculiar details.

The purpose of this class is to be minimalist and completely independent in a way that the game creator only has to use

features from the GameBox and accessory classes and java.lang obviously. Im aiming at guiving game creators a BlitzBasic or

DarkBasic easy of use feeling with these interfaces.

I have made a sketch for the principal interface:

[zingbat]

interface class GameBox {

/* ****************************** Resources ********************************/

public void decode(Resource& resource, URIConnection& uri);
public void encode(Resource& resource, URIConnection& con);

/* ******************************* Media ***********************************/

public void makePlayer(MediaPlayer& player, Resource& reso);

/* ****************************** Drawing **********************************/

public void makeCanvas(Canvas& cvs);
public void makeCanvas(Canvas& cvs, int x, int y, int width, int height);

/* ******************************* Events **********************************/

/**

• Identifies a button or key.
  */
  enum BUTTON_ID {
  MOUSE_LEFT,
  MOUSE_RIGHT,
  MOUSE_MIDDLE,
  VK_0,
  …
  VK_1,
  VK_A,
  …
  VK_Z,
  VK_F1,
  …
  VK_F12,
  VK_ESC,
  VK_TAB,
  VK_CAPSLOCK,
  VK_LEFT_SHIFT,
  VK_RIGHT_SHIFT,
  VK_LEFT_CONTROL,
  VK_RIGHT_CONTROL,
  VK_LEFT_ALT,
  VK_RIGHT_ALT,
  VK_RETURN,
  VK_ENTER,
  VK_SPACE,
  VK_INSERT,
  VK_DELETE,
  VK_HOME,
  VK_END,
  VK_PAGE_UP,
  VK_PAGE_DOWN,
  VK_PRINT_SCREEN,
  VK_SCROLL_LOCK,
  VK_PAUSE,
  VK_UP,
  VK_DOWN,
  VK_LEFT,
  VK_RIGHT,

VK_BAR,
VK_BACKSLASH,
VK_SLASH,
VK_BACKSPACE,

};

/**

• Describes button states.
  */
  enum BUTTON_STATE {
  BUTTON_RAISED,
  BUTTON_LOWERED,
  BUTTON_LOCKED,
  BUTTON_UNLOCKED
  };

/**

• Descriminates between diferent system events.
  */
  enum SYSTEM_EVENT_TYPE {
  SYSTEM_EVENT_STARTING_UP,
  SYSTEM_EVENT_SHUTING_DOWN,
  SYSTEM_EVENT_STARTUP,
  SYSTEM_EVENT_SHUTDOWN,
  SYSTEM_EVENT_SUSPEND,
  SYSTEM_EVENT_RESUME
  };

/**

• Descriminates between diferent viewport events.
  */
  enum VIEWPORT_EVENT_TYPE {
  VIEWPORT_EVENT_RESIZE,
  VIEWPORT_EVENT_VISIBLE,
  VIEWPORT_EVENT_INVISIBLE
  };

/**

• Descriminates between diferent media events.
  */
  enum MEDIA_EVENT_TYPE {
  MEDIA_EVENT_START,
  MEDIA_EVENT_STOP,
  MEDIA_EVENT_PAUSE,
  MEDIA_EVENT_RESUME
  };

/**

• Callback for system change events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
• @param type the specific system event

*/
public void processSystemEvent(long timestamp, SYSTEM_EVENT_TYPE type);

/**

• Programmatically raise a new system event.
  */
  public void postSystemEvent(long timestamp, SYSTEM_EVENT_TYPE type);

/**

• Callback for viewport (gui window) change events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
• @param type the specific viewport event
• @param vp_x the new x coord of the viewport
• @param vp_y the new y coord of the viewport
• @param vp_width the new width of the viewport
• @param vp_width the new height of the viewport

*/
public void processViewportEvent(long timestamp,
VIEWPORT_EVENT_TYPE type,
int vp_x, int vp_y, int vp_width, int vp_height);

/**

• Programmatically raise a new viewport event.
  */
  public void postViewportEvent(long timestamp,
  VIEWPORT_EVENT_TYPE type,
  int vp_x, int vp_y, int vp_width, int vp_height);

/**

• Callback for screen change events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
• @param width the new width of the screen
• @param height the new height of the screen
• @param depth the new color depth of the screen or -1 if nothing changed
• @param fullscreen 0 if changed to windowed mode, 1 if changed to fullscreen
  */
  public void processScreenEvent(
  int width, int height, int depth, int full_screen);

/**

• Programmatically raise a new screen event.
  */
  public void postScreenEvent(
  int width, int height, int depth, int full_screen);

/**

• Callback for keyboard change events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
• @param id the id of the key that changed
• @param state the state to which it changed
• @param asci_code the asci code of the key that was pressed

•               (aware of the shift or caps modifiers)
  

*/
public void processKeyboardEvent(long timestamp,
BUTTON_ID id, BUTTON_STATE sate, int asci_code);

/**

• Programmatically raise a new keyboard event.
  */
  public void postKeyboardEvent(long timestamp,
  BUTTON_ID id, BUTTON_STATE sate, int asci_code);

/**

• Callback for mouse button change events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
• @param id the id of the mouse button that changed
• @param state the state to which it changed
  */
  public void processMouseEvent(long timestamp,
  BUTTON_ID id, BUTTON_STATE state);

/**

• Programmatically raise a new mouse button event.
  */
  public void postMouseEvent(long timestamp,
  BUTTON_ID id, BUTTON_STATE state);

/**

• Callback for mouse motion change events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
• @param x_coord the new screen x location of the mouse
• @param y_coord the new screen y location of the mouse
  */
  public void processMouseMotionEvent(
  long timestamp, int x_coord, int y_coord);

/**

• Programmatically raise a new mouse motion event.
  */
  public void postMouseMotionEvent(
  long timestamp, int x_coord, int y_coord);

/**

• Callback for redraw events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
  */
  public void processRedrawEvent(long timestamp);

/**

• Programmatically raise a new redraw event.
  */
  public void postRedrawEvent(long timestamp);

/**

• Callback for playing media events.
• @note See also class documentation for generic information on events.
• @param timestamp time at which the event was raised
• @param type the specific media event
  */
  public void processMediaEvent(long timestamp,
  MEDIA_EVENT_TYPE type, int ps_id, int frame, int skip);

/**

• Programmatically raise a new media event.
  */
  public void postMediaEvent(long timestamp,
  MEDIA_EVENT_TYPE type, int media_id, int frame, int skip);

}

[zingbat]

public interface GfxCanvas {

/* ****************************** Drawing **********************************/

// cartesian coord system (ox,oy) is lower-left
public double windowOX();
public double windowOY();
public double windowWidth();
public double windowHeigt();

public int viewportLeft();
public int viewportRight();
public int viewportTop();
public int viewportBottom();

public int deviceWidth();
public int deviceHeight();

public void setWindowViewportTransform(
double ox, double oy, double width, double heigth,
int bottom, int left, int right, int top);
public void setIdentityAffine();
public void translate(double x, double y);
public void rotate(double x, double y);
public void scale(double x, double y);
public void push();
public void pop();

public void usePattern(ImagePattern pat);
public void useBitPattern(long[]);
public void useLineStyle(LINE_STYLE style);
public void useFillStyle(FILL_STYLE style);

public void useGfxWriteMode(GfxWriteMode mode);
public void useTransparentColor(Color color);
public void useBackgroundColor(Color color);
public void useForegroundColor(Color color);

public void usePenSize(double size);
public void useFigure(Figure fig);
public void useGfxFont(GfxFont font);

public void begin();
public void end();
public void close();
public void line(double x0, double y0, double x1, double y1);
public void reline(double x0, double y0, double x1, double y1);
public void curve(double x0, double y0, double x1, double y1, double arch);
public void recurve(double x0, double y0, double x1, double y1, double arch);
public void curve2(double x0, double y0, double x1, double y1, double a1, double a2);
public void recurve2(double x0, double y0, double x1, double y1, double a1, double a2);

public void plot(double x, double y);
public void fill();
public void stroke();

}

[zingbat]

Utility classes:

URI, URIConnection, Resource, MediaPlayer, Canvas, Color, RGBColor, ARGBColor, Matrix3, GfxWriteMode, GfxFont, Movie, Sound,

Midi, Image, ImagePattern, Text, Figure, ImageFigure, TextFigure, Polygon, CompositeFigure

An example of usage:

GameBox gbox = new GameBox;

We can use gbox for eveything related to audio, video, events, files, anything system dependent we need in the game.

Using gbox works like this:

GfxCanvas cvs = new GfxCanvas();
gbox.makeCanvas(cvs);
// using a WindowViewportTransform makes the game
// independent of resolution
// we work at a virtual resolution of 800x600 and don’t
// bother at which resolution the game is being played,
// windowed or fullscreen, etc…
cvs.setWindowViewportTransform(
0.0, 0.0, 800.0, 600.0,
0, cvs.deviceHeight(), cvs.deviceWidth(), 0);
// now we can draw images, text, anything
cvs.useGfxFont(someFont);
cvs.useBackgroundColor(whiteColor);
cvs.useForegroundColor(blackColor);
cvs.useGfxWriteMode(opaqueWriteMode);
cvs.useFigure(new TextFigure(“some text”));
cvs.translate(10.0, 10.0);
cvs.scale(8.0, 8.0);
cvs.fill();

// now to play some music

URIConnection con = new URIConnection();
Resource myMusicResource = new Resource();
MediaPlayer myMusicPlayer = new MusicPlayer();

con.open(“mymusic.mp3”);
gbox.decode(myMusicResource, con);
con.close();
gbox.makePlayer(myMusicPlayer, myMusicResource);

myMusicPlayer.config(MPP_MAX_VOLUME, 0.5);
myMusicPlayer.start(); // music starts playing in another thread

[zingbat]

Need help doing this stuff or a similar interface following the some guidelines:

-> minimalist, one main interface and a few accessory classes

-> has everything required to make games (uses one of the availables opengl bingings for opengl calls)

-> isolates from each specific platform and requires only access to java.lang externally (no awt needed, no java2d, etc)

-> easy of use feeling with clean interfaces

[princec]

This is pretty much what the LWJGL does. Code to the LWJGL API properly and you should have an app that’ll run unmodified on a console or a PC.

Cas

[zingbat]

LWJGL is a binding to opengl and opengl is still too complex to learn for many people. This interface provides the bare minimum without taking away the window-viewport transform facility. Plus by wraping everything in one user-friendly interface the game creator has everything he needs without relying on complex java apis for simple stuff. Its everything made into one clean and user-friendly interface: thus the name GameBox.

You could help by implementing this interface in a class that uses LWJGL plus some external apis of your choice for creating the window, the MediaPlayer, the encode/decode functions, etc. The point is not to have an api that can be used to do games (there are many already) its to have a as simple as possible user-friendly interface that provides everything the game creator needs.