Ng -- Overview of Available Core
Services
For questions about this document or this project contact Thomas Seufert at seufet@users.sourceforge.net.
Entity/Event
Model Specifications
References
to Views of Variant Manager Data
Displaying
the Board – Camera and CameraModel
The purpose of the Core component of the Ng Java Roguelike Engine is to provide functionality that assists in architecting and implementing games without imposing extensive structural requirements on the program using it. Although extensive integration services are available in the GameContext, developers are free to use certain or even single portions of the Core, while ignoring the rest.
The Core is comprised of packages that fall into two basic categories:
This document provides an overview of the different functionality provided by the Ng Core. For some components, such as the Plug-in architecture, other documents providing greater detail are referenced.
The first type of package specifies objects, such as the Board, and their event interactions in as minimalist as possible a fashion.
The Board class, for example, has one method, place(Creature,Locator), for inserting a Thing into it, despite the fact that almost all games will wish for functionality that will find a random legal location for a monster and place it there. SimpleGame, the Ng prototype game defines such utility methods, but because their precise nature could vary considerably from game to game, they are not included in the Core.
Furthermore, the Board class defines events that it can
broadcast, such as the fact that a creature has changed location. Rather than update the display itself, Board
relies on an implementation of BoardListener being
added to it which will update the display when a creature moves. This is an example of another guiding
principle of all Core components; loose
coupling. Using this paradigm, it is
equally valid to attach five different displays to a single Board as it is to
attach zero. Most games will want one or
two, but the developer has the flexibility to choose whichever is best.
The second package type defines classes which provide some sort of functionality useful in many (but not necessarily all!) RL games. For example, the rle.core.board.path package defines the abstract class Path, which is a base class for classes representing an ordered traversal of locations in a Board. A traversal could be something as trivial as a line between two points, or as complex as the field of view of the Player, accounting for line-of-sight, blindness, and lighting. Subclasses of Path, such as rle.core.board.path.CirclePath, which models filled or unfilled circles, can be implemented to generate Paths for use in building the board, resolving field-of-view, or determining the path and detonation region of a fire ball.
The class rle.core.board.Thing is
the abstract superclass for all objects that can be
added to the Board, ie the player, npc’s, items, and terrain.
The rle.core.GameContext interface provides a valuable service as an integrator for various Core capabilities. It is available from all Plug-ins and Variant Manager Views via the method getContext() or for subclasses of rle.core.vm.PlugInBase as the protected member “context”. It is expected that most developers will wish to follow SimpleGame’s example and implement GameContext as their variant’s “main” class. Note that rle.core.GameContextBase provides a basic implementation and can be subclassed as in SimpleGame:
public class SimpleGame extends GameContextBase {
What follows are brief overviews of each of the Core
components available from the GameContext.
The GameContext provides two methods that allow access to the currently loaded Variant Manager project:
public InfoGroupView data();
data() returns a read-only view of the root node of the project, which contains the project’s data. This will be the most common method of obtaining a view from which to perform searches on other nodes. For example:
InfoView builderInfo = context.data().findInfo("plug-ins/board-builder");
This line of code could be used to access the node “root/info/plug-ins/board-builder”, which configures the BoardBuilder Plug-in. See “Using the Variant Manager API” for details of how to use this handle.
The rle.core.World interface is
used to retrieve or create instances of Board.
Implementations can determine how a Board is loaded in any way they see
fit – over a network, using a PlugIn, reading from a
file, etc.
The GameContext can store a handle to the Board that the Player is currently exploring. This handle can be accessed by the method currentBoard().
The rle.core.board.Board class provides support for a 2D board with the following attributes:
-Arbitrary, unlimited height and width
-Creatures of unlimited, square size (1x1,2x2,3x3,etc)
-Items of size 1x1
-Terrain, of unlimited, square size
-Events broadcast when things are added or removed
This class can be subclassed by developers who want specialized capabilities.
The GameContext can store a handle to the current Player. This handle can be accessed by the method currentPlayer().
A Perspective is a class which implements rle.core.ui.Perspective, and controls the user experience at a particular time in the game. SimpleGame uses several Perspectives; one displays the “Game” view while playing, and three other, simpler Perspectives display the HTML content that makes up the Welcome, Death, and Victory screens. The Core provides the rle.core.ui.TextFilePerspective class as a utility for Perspectives whose primary presentation is an HTML page, RTF or text file.
The most important method in Perspective is getComponent(), which provides the UI Component which will be added to the main window for the user to interact with.
The current perspective can be accessed from the GameContext using the method currentPerspective(). Note that the Perspective is a “view” class, and not a “model” class. As such, one Perspective can be swapped out for another at any time without changing the state of the game. For example, in SimpleGame, when the graphics mode is changed, a new Perspective is created and used without changing which keymappings are active for player actions.
Three classes in rle.core.board provide immutable alternatives to the java.awt classes – RLRectangle, RLPoint, and RLDimension. Their immutability allows them to be shared and cached, greatly simplifying many operations. These classes also add several convenience methods for easy use.
The rle.core.ui.CameraModel interface specifies an API for modeling what is available for display to the user for a region on the Board. Anything which the player is aware of is “known”; not all “known” things are necessarily displayed, however; that is up to the Camera. The Camera is a purely visual component, which renders the things indicated to be known by the CameraModel. It is the Camera which determines whether any or all of what is known for a location is actually displayed to the user; for instance, a specialized camera could just draw terrain, or debugging information such as light levels.
The GameContext method variant() provides a read-only rle.core.vm.Variant
object with information about the current Variant’s name, version, languages,
and more.
Ng provides support for games which would like to be available in different languages, eg English, Spanish, or French. The Variant Manager provides services for capturing text data in multiple languages; the Core provides services for retrieving that data in the desired language. For details, see Using The Variant Manager API”.
Pains have been taken to implement SimpleGame in both English and Spanish, with the specific intent of providing an example of internationalizing an Ng game.
The rle.core.event.GameClock class provides functionality for timing events such as player and creature movement, night and day, and item recharging. Listeners implementing the GameClockListener interface may be attached to GameClock to make use of its scheduling services. The GameClock class provided implements a scheme in which it can be notified when the player’s turn ends, at which point it fires “ticks”, or game cycles, after each of which it energizes the Player a bit. Listeners detect these “ticks” and can react by performing any scheduled operation desired. This continues until the Player has sufficient energy to move again, at which point the Game Clock waits for another notification that the Player has finished a turn.
Almost all Roguelike games will need some means of delivering messages to the user concerning what is happening in the game. The rle.core.event package defines several classes which make implementing such a system a snap.
The GameContext can retrieve a handle to a single MessageQueue object using the messageQueue() method. The MessageQueue class can accept posted Message subclasses, and notify listeners that a new Message has been posted. The SimpleGame MessageBar class makes use of this functionality to implement a monochrome, scrolling message bar, but other setups are possible, including the single-line system used by Angband, or a WarCraft-like system where messages are super-imposed on the Board view.
The class rle.core.ui.CommandSet abstracts a mapping of the currently available actions that the user can take and the key strokes that cause each action. The CommandSet class can be configured in two ways:
1. From a list of commands in the Variant Manager, as is the case with the “root/info/command-sets/board-normal” CommandSet used in SimpleGame
2. By writing code that creates the mappings, as rle.simple.action.ItemCommands does to handle key presses that toggle the table showing available items, cancel the action, or select an item.
In either case, the current command set can be set by calling GameContext.setCommandSet(). As an implementation note, CommandSet uses the Swing classes ActionMap and InputMap to apply key to action mappings to the main Perspective component. This *greatly* reduces the effort required, and seems to work quite well in SimpleGame.
Interested classes can implement GameContextListener to receive notifications of GameContext events. As of NG 0.2.0, events are fired when the user changes languages, the command set changes, or the Board changes. Listeners can be added and removed via the corresponding methods in GameContext.
Defines classes such as Creature, Monster, Item, and Terrain that provide basic support for these entities. Each of these subclasses Thing, a superclass providing functionality common to all classes which can be placed in a Board.
Provides support classes for items, including the base class ItemContainer and its listener/events. ItemContainer defines a mutable set of items which broadcasts events about changes to its contents, and can serve as a base class for specialized implementations such as a Player’s inventory, equipment, and the items held in a Board location.
Also provided is the ItemContainerTable class, intended to serve as a base class for classes that provide a visual representation of the items in an ItemContainer, for example, the Player’s inventory.
As described above, the Path and PathStep classes provide a common, convenient means of representing traversals of Board locations useful in calculating areas of affect, building mazes, establishing line-of-sight, and more.
Provides the useful RuntimeData class and events. This package is designed to work with the Variant Manager to create hierarchies of dependencies among pieces of data and specify how and when certain values are to be computed.
There are four types of Runtime Attributes:
Consider an example familiar to many Roguelike games – Max Hp. In most Roguelikes, the maximum hit points the player can have is affected by several factors – Constitution, Experience Level, Temporary magical bonuses, Player race, and possibly others. Because Max Hp obviously depends on other attributes, it would be a computed attribute. Something like Cur Hp, on the other hand, cannot be computed from other attributes – its value would probably be stored in a save file, and therefore it would be a persistent attribute. Finally, reference values, such as a constant modifying how much Constitution should affect Max Hp, would be constant attributes. The affect on Max Hp for a particular value of Constitution could be stored in a constant number table.
The Variant Manager provides support for working with Runtime Data via the editor rle.core.data.AttributeTypeCombo.
For detailed examples of this package in action, see “SimpleGame”.
Provides several classes useful for creating the user experience. In particular, the Camera class abstracts the functionality needed to render a view of the Board, and RuntimeAttributeLabel is a component that can listen to a RuntimeData instance and update its display when a given value changes. This class is used by SimpleGame for all stat displays.
Provides classes for read-only access to Variant Manager data. This package is
gone over in detail in “Using The Variant Manager
API”. This package also provides
functionality for working with Plug-ins; see “Programming With
Plug-ins” for more information.
|
Revision Date |
User |
Comments |
|
|
Thomas Seufert |
Created |
|
|
Thomas Seufert |
Update for
0.0.9 |
|
|
Thomas Seufert |
Update for
0.1.0 |
|
|
Thomas Seufert |
Update for
0.2.0 |