Category Archives: Java

Functional programming, closures and higher order functions in Java

Somehow exploratory programming (which is what I am doing to learn about game programming) seems to be much easier when coding in a functional style (if that really is what I think it is :-)). I don’t know the domain yet, I don’t even know what kind of game I’m making and creating class hierarchies did not quite work so far. Apparently all I need is a placeholder for some code and a way to pass it around and even if Java is not really interactive I am already making very good progress. I will post more about this in the near future, but for now here are the basics of what I’m doing.
Also this approach has been described before and I’m not claiming it’s original, this is just my take on it and I’m posting it because it is how I ended up coding for my game.

Java is not a functional language (thank you Captain Obvious) but fortunately there is just enough support in the language to build the rudiments needed for programming in a functional style. The most basic thing we need is a function object or a functor and in Java this can be expressed as a single method interface. Here is a functor that takes an argument of type A1 and returns a result of type R.

public interface Functor1 R invoke(A1 a1);

}


Java does not support variable length optional arguments and the only way I know to get around this is to define Functor2 and Functor3 and so on, just define all the variations you need…

public interface Functor2 {

R invoke(A1 a1, A2 a2);
}
public interface Functor3 {
R invoke(A1 a1, A2 a2, A3 a3);
}

The mandatory trivial example, a simple functor that adds two integers:

class Adder implements Functor2 {

@Override
public Integer invoke(Integer a1, Integer a2) {
return a1 + a2;
}
}
...
Adder adder = new Adder();
adder.invoke(2, 3);

Here is a slightly more complex and more “functional” example, the makeAdder function is what it’s called a higher-order function that creates a functor containing the implementation of the add operation. This implementation is contained in an anonymous inner class that will be completely hidden from the outside world and only available through it’s functor interface.

Functor2 makeAdder() {

return new Functor2() {
@Override
public Integer invoke(Integer a1, Integer a2) {
return a1 + a2;
}
};
}
...
Functor2 adder = makeAdder();
adder.invoke(2, 2);

I know it looks ugly but after using this stuff for a while the unimportant boiler plate code kinda fades away and I only see the function code, pretty much the same way LISP coders don’t notice parentheses anymore.

More complex scenarios can be handled with proxies and introspection, preprocessing with apt or maybe even code generation with something like cglib but so far I did not really have a need for something like that. So there you have it, first-class functions in Java, this is pretty much all that is needed to support closures and higher order functions.

Now that we have pseudo first-class functions closures are relatively easy, in Java a closure can simply be simulated as an anonymous inner class and such a class gets access to the enclosing class members and also the local final variables. (You have probably already used closures disguised as various Java “callbacks” and things like the Runnable interface…)
Here is an example of a function that creates three functors that manipulate an “item database”. (If I remember correctly similar examples have been presented in various LISP books.)

void doSomething() {

final Map itemDb = new HashMap();

Functor2 addItem = new Functor2() {
@Override
public Item invoke(String name, Item item) {
itemDb.put(name, item);
return item;
}
};
Functor1 getItem = new Functor1() {
@Override
public Item invoke(String name) {
return itemDb.get(name);
}
};
Functor1 removeItem = new Functor1() {
@Override
public Item invoke(String name) {
return itemDb.remove(name);
}
};

doSomethingWithTheItems(addItem, getItem, removeItem)
}

void doSomethingWithTheItems(Functor2 addItem, Functor1 getItem, Functor1 removeItem) {
addItem.invoke("item1", new Item());
...
}

Observe how the database manipulation functors can be passed to other parts of the code that do not know anything about a hash map that exists somewhere to hold the items.

One more thing, it is not possible to change a final variable, so for instance a primitive value cannot be changed from inside a closure. The workaround is wrapping that variable in a mutable container, I have seen this emulated with a single element array but I use the class below:

public class Reference {

public K v;

public Reference(K v) {
this.v = v;
}

@Override
public String toString() {
return v.toString();
}

@Override
public boolean equals(Object obj) {
return v.equals(obj);
}

@Override
public int hashCode() {
return v.hashCode();
}
}
final Reference var = new Reference(1);

Functor incVar = new Functor() {
@Override
public Integer invoke() {
var.v++;
return var.v;
}
};
incVar.invoke();

This is all, for additional information on the benefits and downsides of functional programming, with or without Java, please consult your nearest search engine.

Did I mention this is an experiment I indulge in? I imagine that most Java programmers will find various flaws but so far it worked well for me and it also seems that as parts of the code get finalized it is pretty easy to convert them to a more conventional Java style. I also know that I could switch to Scala or Clojure (I have used Clojure before but not Scala) but for now I will just wait for Java 7.

Simple JavaScript Console

Here are more details on the console thingy seen in my post about scripting, it’s nothing terribly special, just a simple UI with a few extras like redirecting System.out/err to the output area in the frame, download the code below and take a look.

Here is how you use it:

public class ConsoleDemo extends Scene2D {
private ImageSprite man, spirit;

@Override
public void load() {
add(new FilledSprite(Colors.WHITE));

man = new ImageSprite("Man.png", 10, 10);
add(man);
spirit = new ImageSprite("Spirit.png", 100, 10);
add(spirit);

ConsoleFrame consoleFrame = new ConsoleFrame();

ScriptEngineManager scriptEngineManager = new ScriptEngineManager();
ScriptEngine scriptEngine = scriptEngineManager.getEngineByName("JavaScript");
scriptEngine.put("demo", this);

consoleFrame.setScriptEngine(scriptEngine);
consoleFrame.setLocation(900, 200);
consoleFrame.setVisible(true);
}

public ImageSprite getMan() {
return man;
}

public void setMan(ImageSprite man) {
this.man = man;
}

public ImageSprite getSpirit() {
return spirit;
}

public void setSpirit(ImageSprite spirit) {
this.spirit = spirit;
}
}

Just make sure you instantiate the ConsoleFrame before the ScriptEngineManager or the System.out/err redirection will not work. Also, the example is PulpCore based but there is no PulpCore dependency in the ConsoleFrame code.

And now a trivial script:

demo.setPaused(true)
println(demo.man)
println(demo.man.x)
demo.man.x.set(200)
println(demo.man.x)
demo.setPaused(false)

Putting an instance in the scripting engine like this scriptEngine.put("demo", demoInstance) makes it available with that name, members that are public or have getters/setters are directly accessible from JavaScript.

And one somewhat important caveat, the Swing code runs in it’s own thread and so does the scripting engine, changing the game state from a script can lead to inconsistencies at times if your code is not thread safe (and likely it is not – usually games are coded single-threaded), to avoid problems first pause the game loop, run the script and make your changes and then resume the loop. For PulpCore you can do this by calling Scene2D.setPaused()

More details and documentation on scripting Java classes at http://www.mozilla.org/rhino/, especially this https://developer.mozilla.org/en/Scripting_Java

Download the source code.

Scripting in Java Games

Having a scripting engine can be invaluable to a game developer but developing one is complex quite time consuming. I have seen various scripting language implementations (including Lisp 🙂 ), everybody seems to forget that Java comes with a perfectly good JavaScript engine ( Rhino) that can be embedded into your game with very few lines of code.

ScriptEngineManager scriptEngineManager = new ScriptEngineManager();
ScriptEngine scriptEngine = scriptEngineManager.getEngineByName("JavaScript");
//add any variables that you want accessible from the scripting engine
scriptEngine.put("gameWorld", this);

There are many uses to scripting, often games keep the entity logic in scripts that get called from the game loop. I use the scripting mostly to tweak and tune Box2D related variables without having to go through the edit/compile/restart cycle.

Here is a little example to give you an idea.

gameWorld.pause()
boidsIt = gameWorld.boids.iterator();
while(boidsIt.hasNext()) {
boid = boidsIt.next();
boid.body.setLinearDamping(10);
boid.body.setAngularDamping(20);
}
gameWorld.resume()

I added a simple interactive editor/console and here how a dev session for my Astroboids game looks like. And yes, I made some progress with my game, this is an actual screen shot of the game running.

And a side note, there are other scripting engines available (BeanShell, Groovy, etc), but they require additional jars, the JavaScript Rhino engine comes bundled with Java 6.

Non-tile based level editing with Box2D, PulpCore and GLEED2D

I implemented some basic game mechanics for Astroboids and I was about to start working on a map editor. First thought was a tile based system that almost everybody seems to be using and then I found this article about an editor that “doesn’t use tiles but pieced images”, very nice stuff but it could take a while to implement. I then came across GLEED2D,  “a non tile-based Level Editor for 2D games of any genre that allows arbitrary placement of textures and other primitive items in 2D space” according to the description on its website. GLEED2D is surprisingly good and easy to use, it saves XML, and of course, it beats having to write my own tool. The XML seems to be simply .Net objects serialized to XML, but hey, Java does XML and it looked like a few XPath expressions could take care of it.

Keep reading for a slightly “beyond the basics” tutorial and demo (it is the XML that makes things a little more complex, that’s all)

So above is what GLEED2D looks like and below is the XML that it generates:


Visible="true">





330
70


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




455
280


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




325
225


0
1

255
255
255
255
4294967295

false
false
Man.png
Man

32
32




80
50


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




85
265


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




515
60


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




475
160


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




190
145


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




370
405


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




130
435


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




245
315


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




520
420


0
1

255
255
255
255
4294967295

false
false
Spirit.png
Spirit

32
32




1
1





13
C:\dev\workspace\GLEED2D Level\res

425.000641
225.0004



Now lets extract what we need out of this XML document. First, an utility class that hides some of the XPath’s ugliness. (for additional info on the “functors” that you see in the code refer to my previous posts here and the LazyCache class is explained here)

public class XmlUtil {
static XPathFactory factory = XPathFactory.newInstance();

static Map xpathExpressions = new LazyCache(64,
new Functor1() {
@Override
public XPathExpression invoke(String query) {
XPath xpath = factory.newXPath();
XPathExpression expr;
try {
expr = xpath.compile(query);
} catch (XPathExpressionException e) {
throw new RuntimeException(e);
}
return expr;
}
});

public static NodeList selectNodeList(Node doc, String query) throws XPathExpressionException {
XPathExpression expr = xpathExpressions.get(query);
return (NodeList) expr.evaluate(doc, XPathConstants.NODESET);
}

public static Node selectNode(Node doc, String query) throws XPathExpressionException {
XPathExpression expr = xpathExpressions.get(query);
return (Node) expr.evaluate(doc, XPathConstants.NODE);
}

public static T selectValue(Class type, Node doc, String query) throws XPathExpressionException {
XPathExpression expr = xpathExpressions.get(query);
if (Number.class.equals(type)) {
Double v = (Double) expr.evaluate(doc, XPathConstants.NUMBER);
if (v.isNaN())
throw new XPathExpressionException("Query " + query + " result is not a number");
return type.cast(v);
} else if (String.class.equals(type)) {
return type.cast(expr.evaluate(doc, XPathConstants.STRING));
} else if (Boolean.class.equals(type)) {
return type.cast(expr.evaluate(doc, XPathConstants.BOOLEAN));
} else {
throw new XPathExpressionException("Unkown data type " + type);
}
}

public static Document readDocumentFromStream(InputStream stream) throws ParserConfigurationException, SAXException,
IOException {
DocumentBuilderFactory domFactory = DocumentBuilderFactory.newInstance();
domFactory.setNamespaceAware(true);
DocumentBuilder builder = domFactory.newDocumentBuilder();
Document doc = builder.parse(stream);
return doc;
}
}

Basically this XMLUtil class lets you write simplified XPath queries like the ones below.

String s = XmlUtil.selectValue(String.class, "@Name");
float x = XmlUtil.selectValue(Number.class, node, "Vector2/X/text()").floatValue();[/cc]

Now that the XML/XPath part is somewhat taken care of here is the class that does most of the work.

public class Gleed2DItem {
private final Node node;

public Gleed2DItem(Node node) throws XPathException {
this.node = node.cloneNode(true);
}

private T property(Class type, String name) {
try {
return XmlUtil.selectValue(type, node, name);
} catch (XPathExpressionException e) {
throw new RuntimeException(e);
}
}

public String name() {
return property(String.class, "@Name");
}

public String type() {
return node.getAttributes().getNamedItem("xsi:type").getTextContent();
}

public boolean visible() {
return property(Boolean.class, "@Visible");
}

public Vec2 position() {
float x = property(Number.class, "Position/X/text()").floatValue();
float y = property(Number.class, "Position/Y/text()").floatValue();
return new Vec2(x, y);
}

public Vec2 origin() {
float x = property(Number.class, "Origin/X/text()").floatValue();
float y = property(Number.class, "Origin/Y/text()").floatValue();
return new Vec2(x, y);
}

public float rotation() {
return property(Number.class, "Rotation/text()").floatValue();
}

public float height() {
return property(Number.class, "Height/text()").floatValue();
}

public float width() {
return property(Number.class, "Width/text()").floatValue();
}

public float radius() {
return property(Number.class, "Radius/text()").floatValue();
}

public int fillColor() {
int r = property(Number.class, "FillColor/R/text()").intValue();
int g = property(Number.class, "FillColor/G/text()").intValue();
int b = property(Number.class, "FillColor/B/text()").intValue();
int a = property(Number.class, "FillColor/A/text()").intValue();
return Colors.rgba(r, g, b, a);
}

public int tintColor() {
int r = property(Number.class, "TintColor/R/text()").intValue();
int g = property(Number.class, "TintColor/G/text()").intValue();
int b = property(Number.class, "TintColor/B/text()").intValue();
int a = property(Number.class, "TintColor/A/text()").intValue();
return Colors.rgba(r, g, b, a);
}

public String textureFilename() {
return property(String.class, "texture_filename/text()");
}

public List customProperties() {
try {
List result = new ArrayList();
NodeList customPropertyNodes = XmlUtil.selectNodeList(node, "CustomProperties/Property/@Name");
for (int i = 0; i Node localPointNode = customPropertyNodes.item(i);
result.add(localPointNode.getNodeValue());
}
return result;
} catch (XPathExpressionException e) {
throw new RuntimeException(e);
}

}

public String customProperty(String name, String notFoundValue) {
return customProperty(String.class, name, notFoundValue);
}

public String customProperty(String name) {
return customProperty(name, null);
}

public T customProperty(Class type, String name) {
return customProperty(type, name, null);
}

public T customProperty(Class type, String name, T notFoundValue) {
String query;
if (Boolean.class.equals(type)) {
query = "CustomProperties/Property[@Name='" + name + "']/boolean/text()";
} else {
query = "CustomProperties/Property[@Name='" + name + "']/string/text()";
}
try {
//empty string means not found
if ("".equals(XmlUtil.selectValue(String.class, node, query)))
return notFoundValue;

T value = null;
if (Number.class.equals(type) || String.class.equals(type) || Boolean.class.equals(type)) {
value = XmlUtil.selectValue(type, node, query);
} else if (Vec2.class.equals(type)) {
float x = XmlUtil.selectValue(Number.class, node,
"CustomProperties/Property[@Name='" + name + "']/Vector2/X/text()").floatValue();
float y = XmlUtil.selectValue(Number.class, node,
"CustomProperties/Property[@Name='" + name + "']/Vector2/Y/text()").floatValue();
value = type.cast(new Vec2(x, y));
} else {
throw new RuntimeException("Unkown data type " + type);
}
return value;
} catch (XPathException e) {
if (notFoundValue != null)
return notFoundValue;
throw new RuntimeException(e);
}
}
}

The Gleed2DItem wraps a GLEED2D XML node and gives you easy access to the relevant bits of it. I will not explain XML and XPath here as there is plenty of documentation and tutorials out there, just ask your favorite search engine for it. It now gets pretty easy to make sprites out of all these items:

Document doc = XmlUtil.readDocumentFromStream(Assets.getAsStream("Level1.xml"));
NodeList nodeList = XmlUtil.selectNodeList(doc, "/Level/Layers/Layer[@Name='Layer1']/Items/*");
for (int i = 0; i Gleed2DItem item = new Gleed2DItem(nodeList.item(i));
Vec2 position = item.position();
CoreImage image = CoreImage.load(item.textureFilename());
Sprite sprite = new ImageSprite(image, (position.x), (position.y));
sprite.setAnchor(0.5, 0.5);
add(sprite);
}

Download the source code.

Building UI with PulpCore

I have been working on a little project that has a slightly more involved UI interface and while PulpCore provides enough widgets there is no easy way of laying out interface elements other that calculating pixel coordinates and sizes.

Anyway, after trying a few things I ended with a little DSL that looks like this:

uiHelper.place(toolbar).in(ui).height(40).spacing(2).top().left().hfill();

The code above places a sprite named toolbar inside a group named ui, positioned at the top/left corner, leaving a margin of 2 pixels and filling all the available space horizontally.

A few more examples:

Button buttonNew = uiHelper.place(
Button.createLabeledButton("New", 0, 0)).in(toolbar).vcenter().spacing(3).left().sprite();

Button buttonOpen = uiHelper.place(
Button.createLabeledButton("Open", 0, 0)).in(toolbar).vcenter().spacing(3).
rightOf(buttonNew).sprite();

uiHelper.place(palette).in(ui).width(250).spacing(2).below(toolbar).right().height(400);

uiHelper.place(timeline).in(ui).spacing(2).below(palette).left().hfill().vfill(palette);

Not too bad, once I got the hang of it things moved pretty quickly. Basically you start with a reference widget and add things to its right/below/whatever, widgets can then be resized to the size of a target sprite or can fill the remaining space using hfill/vfill.

The DSL is “imperative”, things are set/executed as soon as the method is called, there is no “do it” command at the end of the “sentence”.

This is the code that does it all in less than 100 LOC, just copy and paste into your project.

package toolkit.pulpcore;

import pulpcore.sprite.Group;
import pulpcore.sprite.Sprite;

public class SpriteHelper {
private Sprite sprite;
private Group container;
private int spacing;

public SpriteHelper place(Sprite sprite) {
this.sprite = sprite;
return this;
}

public SpriteHelper in(Group container) {
this.container = container;
container.add(sprite);
return this;
}

public SpriteHelper spacing(int spacing) {
this.spacing = spacing;
return this;
}

public SpriteHelper top() {
double y = spacing;
sprite.y.set(y);
return this;
}

public SpriteHelper bottom() {
double y = container.height.get() - sprite.height.get() - spacing;
sprite.y.set(y);
return this;
}

public SpriteHelper left() {
double x = spacing;
sprite.x.set(x);
return this;
}

public SpriteHelper right() {
double x = container.width.get() - sprite.width.get() - spacing;
sprite.x.set(x);
return this;
}

public SpriteHelper rightOf(Sprite target) {
double x = target.x.get() + target.width.get() + spacing;
sprite.x.set(x);
double y = target.y.get();
sprite.y.set(y);
return this;
}

public SpriteHelper leftOf(Sprite target) {
double y = target.y.get() - sprite.width.get() + -spacing;
sprite.y.set(y);
double x = target.x.get();
sprite.x.set(x);
return this;
}

public SpriteHelper below(Sprite target) {
double x = target.x.get();
sprite.x.set(x);
double y = target.y.get();
y += target.height.get();
y += spacing;
sprite.y.set(y);
return this;
}

public SpriteHelper hcenter() {
double x = container.width.get() / 2 - sprite.width.get() / 2;
sprite.x.set(x);

return this;
}

public SpriteHelper vcenter() {
double y = container.height.get() / 2 - sprite.height.get() / 2;
sprite.y.set(y);

return this;
}

/**
* Fill all the horizontal container space
*
* @return
*/
public SpriteHelper hfill() {
sprite.width.set(container.width.get() - spacing * 2);
return this;
}

/**
* Fill the remaining space to the right of the target
*
* @param target
*/
public void hfill(Sprite target) {
sprite.width.set(container.width.get() - target.x.get() - target.width.get() - 2 * spacing);
}

/**
* Fill all the vertical container space
*
* @return
*/
public SpriteHelper vfill() {
sprite.height.set(container.height.get() - spacing * 2);
return this;
}

/**
* Fill the remaining space below the target
*
* @param target
*/
public SpriteHelper vfill(Sprite target) {
sprite.height.set(container.height.get() - target.y.get() - target.height.get() - 2 * spacing);
return this;

}

public SpriteHelper height(double h) {
sprite.height.set(h);
return this;
}

public SpriteHelper width(double w) {
sprite.width.set(w);
return this;
}

@SuppressWarnings("unchecked")
public T sprite() {
return (T) sprite;
}
}

Simple Java Tip: Lazy Loading HashMap

I am pretty sure you have seen this “lazy loading”/caching Java idiom or one of it’s many alternatives quite often:

Map cache = new HashMap();

public Entity getItem(String name) {
if(!cache.containsKey(name)) {
cache.put(name, new Entity(name));
}
return cache.get(name);
}

Here is another way of doing the same thing, the LazyHashMap calls the lazyHandler when it needs to get a missing value:

public class LazyHashMap extends HashMap{
private Functor1 lazyHandler;

public LazyHashMap(Functor1 lazyHandler) {
this.lazyHandler = lazyHandler;
}

@Override
public V get(Object key) {
if (!containsKey(key)) {
K k = (K) key;
put(k, lazyHandler.invoke(k));
}
return super.get(key);
}
}


Functor1 is simple interface:

public interface Functor1 {
R invoke(A1 a1);
}

A decorator pattern could be used instead of extending the HashMap class.

class LazyMapDecorator implements Map {
private final Map m;
private final Functor1 lazyHandler;

public LazyMapDecorator(Map m, Functor1 lazyHandler) {
this.m = m;
this.lazyHandler = lazyHandler;
}

public V get(Object key) {
if (!containsKey(key)) {
K k = (K) key;
m.put(k, lazyHandler.invoke(k));
}
return m.get(key);
}
...

And here is an example:

LazyHashMap entityCache = 
new LazyHashMap(new Functor1() {
@Override
public Entity invoke(String a1) {
return new Entity("Bozo");
}
});

entityCache.get("Bozo");

This trick lets you retrofit caching into your code without having to encapsulate the map calls into “accessor” like methods, just decorate an existing map or change it to a lazy one.

This technique is an example of functional programming in Java, read my previous post or ask a search engine about it.

Simple Java Tip: Checked Type Casting

This is quite a trivial trick but it is very useful at times and I do not remember seeing it in any of the game related code sample I have read so far, so here it is.
Sometimes you get an object from somewhere and you know what type it should be and what to do if it’s not of that type (and by the way, if this is a common occurrence in your code it may be a hint that you should review your OO design). The usual java idiom to handle the situation is something like this:

if (o instanceof Something) {
s = (Something) o;
} else {
s = null;
}

Simple enough but if you have to do it a lot becomes kind of annoying. Here is a solution:

public class Cast {
public static T as(Class type, Object o) {
if (type.isInstance(o))
return type.cast(o);
return null;
}
}


And you can now write:

Something s = Cast.as(Something.class, o);
if(s != null) {
...
}

Bonus: if you’re getting objects from a heterogeneous map, create a simple delegating map wrapper that adds a casting get operation. I use this fairly frequently in my game code where entities have heterogeneous maps to hold their properties.

public class CastingMap implements Map {
private final Map m;

public CastingMap(Map m) {
this.m = m;
}

public T get(Class type, K key) {
return Cast.as(type, get(key));
}
...