Java Checked vs Unchecked Exceptions


Today I have decided to write an article not so related to game development (yes, JevaEngine is coming along very nicely in-case you are wondering.) Instead I will be focusing on the difference between checked and unchecked exceptions, what the general consensus is on them and my opinion on them.

First, lets define quickly the differences between the two types of exceptions and what their intentions are, then I will go through my experiences with either one and where I rest my opinions now.

Checked Exceptions vs Unchecked Exceptions

An unchecked exception is your conventional exception. It can be thrown from anywhere, and it can be declared in a try-catch clause anywhere. Some typical examples of this are (in the JDK) IndexOutOfBoundsException, IllegalArgumentException etc... These exceptions are thrown when the programmer is using a particular interface incorrectly.

For example, the following code will throw an unchecked NullPointerException, opposed to a checked FileNotFoundException.

String fileName = null;
try(FileInputStream fis = new FileInputStream(fileName))
} catch (IOException e) { }

Checked Exceptions are used to describe errors that may occur, and their ability to occur is entirely out of the hands of the programmer using the interface throwing them as well as the interface implementation itself. That is to say that even if the interface is used 100% properly, and its implementation is 100% free of bugs, it still may encounter an error performing its task. So for example, you could reconsider the FileNotFoundException shown above. Whenever you open a file, you must deal with the possibility that it does not exist. Whenever you open or read from a file, you must deal with the possibility that an IOException occurred when attempting to gain access to the files data.

Where it gets interesting

Sometimes you will encounter situations where a checked-exception being thrown by an interface should be, in your very particular circumstance, interpreted as a unchecked exception. These are *rare* - and you should almost never do what I am about to show you (if you don't think checked exceptions are evil - otherwise you probably already do it all over the place...)

Consider the following code sample:

try {
	URI files = new URI("file:///a/b/c.txt");
} catch (URISyntaxException ex) {
	//This will never happen

In this case, we are providing the constructor of URI a valid syntactically correct URI, but we are still forced for catch the checked exception. In our particular circumstance, since the URI String is being defined by the programmer, this is actually an unchecked exception. As per our definitions above.

In that code sample, what we are doing is converting a checked exception to nothing. This is _very_ _very_ bad. This means that if someone comes along and changes that syntactically correct URI String to something syntactically incorrect, no one will ever know. They will get a NullPointerException when trying to reference the URI. Instead it is better to rethrow the exception as an Unchecked Exception.

try {
	URI files = new URI("file:///a/b/c.txt");
} catch (URISyntaxException ex) {
	throw new RuntimeException(ex);

Again, converting from an checked exception to an unchecked exception should be done with very careful consideration.

Now that I've made my point, URI actually provides a static convenience method for doing something very similar to this:

URI files = URI.create("file:///a/b/c.txt");

Scenario Drivers

I've come up to a reasonable solution to make the development of scenarios in JevaEngine significantly simpler and comfortable. First, we must define what a scenario is.

A scenario, in abstract terms, describes a series of events (as well as a sequence in which they must take place) and how the world reacts to the occurrence of these events. Scenarios can be incredibly simple or very complex. Typically, they are constructed by associating concrete behavior to particular entities. Ie, the logic of the scenario is not centralized but rather scattered across various entities.

Consider the following example scenario where in the player must kill a goblin, acquire a key from their corpse and then open a door. In this example, the behavior might be distributed as such:

You might construct a special item called "Key to Door Y." The key in-itself has no behavior and is merely a means for the critical components in the scenario (the goblin and the door) to communicate. The key is uninteresting to the player once he passes Door Y and outside of this function it serves no purpose.

The goblin may be a typical NPC. It could be one you spawn like all others, but it would require at least some specific configuration for its act in this scenario. It might be a configuration you call 'questGoblinDoorY' with the behavior adding the special key to its inventory.

The door would need to have a tailored behavior to open only under the circumstance that the player has the required key.

As you can imagine, the development of such a simple scenario ends up become very tedious. Now imagine multiple scenarios occurring in the same scene. That makes the development process significantly worse and stressful.

As a means to centralize the configuration of scenarios, I have decided to develop and use ScenarioDriver entities. They drive a scenario described in freemind. Here is a sample scenario I have developed thus far in freemind.

Using XSLT, I intend to transform this into a format that can be parsed by the Scenario Driver entity.

The victim's hotel room...

May be worth investigating the victim's hotel room.

Design your dialogue in JevaEngine using freemind.

I have written a custom XSLT (along with several changes to the dialogue system in the RPG base) that allows you to design your character dialogue in an mind-mapping utility called FreeMind. Here is quick demonstration (I'm short on time, and a picture is worth a thousand words...)

Note that the dialogue you are about to see demonstrated is meant to project a real murder case, and is thus graphic in nature.

A screenshot of Demo3

Demo 3 is getting really close to being completed. There are a few issues/bugs to resolve.

Demo3 uses PARPG assets to construct an "investigation" quest. Unlike Demos 0-2 which are more action rpg orientated using the FLARE RPG assets.

Imported PARPG assets for demo, improved rendering system a bit

As you may know, ISceneBuffer objects are responsible for handling rendering in JevaEngine. Today I've found some time to add a new ISceneBuffer object to JevaEngine's core. There are now two ISceneBuffers built into JevaEngine (it is very easy to use your own.)

- PaintersIsometricSceneBuffer which uses the painter's algorithm for rendering isometric scenes. This method is very quick but frequently fails if your scenes are not composed of strictly fixed sized blocks. It sorts based on the location of the entity - but ignores the containing bounds of that entity. Thus this makes it impossible to depth sort walls or gates that span across multiple tiles properly without breaking them into individually size tiles.

- TopologicalIsometricSceneBuffer is much more proper in terms of depth sorting scene components. It works with variable sized components and allows entities to be sorted properly on the Z axis. However, this sorting algorithm is much more expensive and has a complexity of O(n^2) That said, I have managed to get very large scene to be sorted in a manner of 1-2ms - which is perfectly acceptable.

Here is a test for the TopologicalIsometricSceneBuffer. You'll see the scene components and their respective AABBs.

There are three components visible in this image, the gas tank, the wind mill and the ground (which is a single component.)

In previous screen-shots, the ground was composed of many different components - each per tile. With this new depth sorting algorithm, the ground can be a single sprite (generated via tiled or rendered out of blender etc...) You can imagine that generating the meta-data on a per-tile basis would be a lot of work (especially if you have a lot of tiles) so it is much more optimal to import them into tiled, construct a tile-able surface texture 20x20 tiles in dimensions use that instead.

Demo 2 - Quest Demo

Demo 2 demonstrates how you could use JevaEngine to implement various quest using a combination of quest-controlled-NPCs, and area triggers to initiate character dialogue. It also demonstrates how to use the dialogue system implemented by the RPG Base.

Below is a layout of our world in the world editor:

In the bottom left corner, you'll see a named entity placement "player." If we look at its import declaration (which can be edited via the GUI in the world editor - but I will list the JSON for convenience.)

    "location" : {
      "z" : 1.0099999904632568,
      "y" : 44.0,
      "x" : 19.0
    "direction" : 8,
    "name" : "player",
    "config" : "artifact/entity/zombie/zombie.jec",
    "auxConfig" : {
      "behavior" : "artifact/behavior/character/puppet.js"
    "type" : "character"

A few sample scripts!

Hey! I've basically got JevaEngine's demos to a near complete state. I thought I would share some of the scripts I have driving the behavior used in the demo.

The first script is called the "puppet" behavior. When used by an RpgCharacter it remains idle until given abstract commands. For example "attack x" or "move to y." Essentially making it a puppet. It is useful in quest scripts where you are controlling special quest characters etc (i.e, to attack the player when they enter a trigger, or speak to the player when they come near etc...) Additionally, it is also used as the player character behavior (since the player's character is a puppet to the player.)

Note that these scripts I am posting are a little hacky/messy. They are more of a means to an end design rather than thoroughly thought through implementations. They are not critical in any sense to the engine or rbgbase. They serve specifically as samples & behaviors for driving the demo. They may contain bugs etc.

var g_attackTarget = null;

var g_attackRange = 0;
var g_attackSound = null;
var g_attackDamage = 0;
var g_attackPeriod = 0;

var g_dieSound = null;

var g_controlQueue = new Queue();

me.onEnter.add(function() {

	//Upon entering a world, initialize with configuration parameters.
	var config = me.getConfiguration();

	if (config.childExists("attackDamage"))
		g_attackDamage = config.getChild("attackDamage").getValueInt();

	if (config.childExists("attackPeriod"))
		g_attackPeriod = config.getChild("attackPeriod").getValueInt();

	if (config.childExists("attackRange"))
		g_attackRange = config.getChild("attackRange").getValueDouble();

	if (config.childExists("attackSound"))
		g_attackSound = config.getChild("attackSound").getValueString();

	if (config.childExists("dieSound"))
		g_dieSound = config.getChild("dieSound").getValueString();


function constructTasks() {
	// Double check to assure we are constructing over a clean slate.

	//If we're dead, there are no tasks that we can do...
	if (me.getHealth() <= 0)

	var controller = g_controlQueue.poll();

	if (controller != null) {
	} else if (g_attackTarget === null || g_attackTarget.getHealth() <= 0) {
		g_attackTarget = null;
	} else {
		var deltaFromTarget = me.getLocation().difference(g_attackTarget.getLocation());
		var distance = deltaFromTarget.getLength();
		if (distance <= g_attackRange) {
		} else
			var targetLocation = g_attackTarget.getLocation();
			me.moveTo(targetLocation.x, targetLocation.y, g_attackRange * 0.95);
			me.invokeTimeout(2000, constructTasks); //reconstruct tasks as it is likely that our target will move.


me.doAttack.assign(function(attackee) {
	var distance = me.getLocation().difference(attackee.getLocation()).getLength();
	if (distance >= g_attackRange)
		return false;

	attackee.invokeInterface("damage", g_attackDamage);

	if (g_attackSound !== null)

	return true;

me.onLookFound.add(function(target) {
	if (me.isConflictingAllegiance(target) && g_attackTarget === null) {
		g_attackTarget = target;

me.onHealthChanged.add(function(delta) {
	if (me.getHealth() === 0) {
		if (g_dieSound !== null)

me.mapInterface("target", function(target) {
	g_attackTarget = target;

me.mapInterface("damage", function(delta) {
	me.setHealth(me.getHealth() - delta);

me.mapInterface("queryControl", function(handler) {
	g_controlQueue.add(new CharacterController(handler));

function CharacterController(handler) {
	this.handler = handler;

CharacterController.prototype.doTasks = function() {

CharacterController.prototype.moveTo = function(x, y) {
	me.moveTo(x, y);

CharacterController.prototype.speakTo = function(subject, dialogue) {
	me.speakTo(subject, dialogue);

CharacterController.prototype.setFlag = function(flag, value) {
	me.setFlag(flag, value);

CharacterController.prototype.idle = function(length) {

Changes to JevaEngine's Scripting System

As you know, there have been some very large refactors in JevaEngine. These have allowed much more flexibility in JevaEngine - specifically the ability to use various different script engines. In this abstracting, I've also had to reorganizing the interface to these scripts. Here are some notable changes:

In the previous implementation of JevaEngine's scripting engine, you would have defined your methods in the global scope (of the script.) These methods would then be identified as handlers/delegates by their container (ie an entity) using their name/signature. There were a couple notable issues with this methods:

1. It littered the script's namespace. One could define a method without the intention of it being a handler, but by virtue of having the proper name/signature, the script's container would recognizes it as an event handler or delegate. For example, consider the onAttacked handler. Previously, it would be defined like so in the behavior script:

function attacked(attacker)
... Some event handling code

It is difficult to determine the purpose of this method. It may be used internally by the script, or it may be an event handler. One may define a method such as this with the intention of having it be used internally, but it would be acknowledged by the script's container (an entity for example) as a handler/delegate.

2. It made developing/debugging more difficult and the errors in scripts more difficult to identify. Failing to register a handler or delegate would be met with no immediate execution errors. One would simply observe absent behavior. For example, had the 'attacked' method above been named 'atttacked' instead (note the typo) the code would execute without any errors or warnings, yet one would observe the attack response behavior to be absent had they the luxury of testing the script in such an environment so readily.

The new method for registering handlers and delegates is much more efficient and resolves both of these issues. One would now do the following to register an 'attacked' handler.

me.onAttacked.add(function(attacker) {
..Handle attacked event

Also note that this allows for various different functions to be assigned to (or 'listen' to) events such as being attacked. Likewise, to register a handler:

me.doAttack.assign(function(attackee) {
..Do attack

You may have also noticed that in recent commits the feature to access a scripts defined methods/variables via the getScript method exposed on an entity's bridge was added. This has since been removed. The Entity Bridge being publicly accessible violated the privacy/control held by the respective behavior script and allows one to create unpredictable changes to the behavior's state/environment without warning. In the upcoming commits, the getScript method has been removed.

However, one will still likely need to obtain some interface/control over an entity externally (such as controlling a player for a quest script.) All entities now have a method called mapInterface (accessible only to the behavior script) and invokeInterface. This allows interface methods to be invoked and mapped, allowing one to control the entity via an interface presented by the entity's behavior script.


Subscribe to JevaEngine RSS