Refactoring The Object System

February 26, 2013|

Welcome to the first development update of Grimrock 2! In this post I’m going to talk about a big internal change under the hood of the engine. The discussion should be especially interesting to modders.

A small disclaimer before we get started: many things that we talk about in these updates are work in progress, incomplete or ideas that may not have been proven in practice to work. Therefore many things could very well change or be removed in the shipping version. We also want to keep some things, especially the puzzles, the plotline and probably most of the monsters as secrets to avoid spoiling the fun. Ok, I think that should be clear, so let’s get rolling!

The object model in the original Grimrock was class based. So, the functionality of torch holders was implemented in the TorchHolder class, statues used the Decoration class, doors the Door class and so on. In a class based system, each class has a fixed set of features: e.g. all instances of Monster class have a 3D model and a set of animations. Also a fixed set of behaviors is typically hardcoded into the class, e.g. the flickering of torches.

There are a number of problems with the class based object model. One problem is code duplication. For example, LightSource, Fireball and Crystal classes all contain some code for handling a light source in the game world. Item, Fireball and other spell classes contain projectile logic. A huge number of classes contain code for setting up the rendering model. Code duplication means that there is a lot more code to debug and maintain than is necessary.

Another classic problem is fitting new features to the class hierarchy. Consider, for example, the Decoration class that was used in Grimrock to implement decorative objects that have no gameplay functionality. The class was used for anything ranging from wall chains to statues. But what if we need an animated statue? Should we add a new class AnimatedDecoration (adding redundant code), or add support for animations to the Decoration class (bloating all decoration instances that do not need animation support)? The problem gets even worse, if we happened to need a statue with animations and a continuous humming sound.

The final nail to the coffin of class hierarchies is rigidity. The features of entities are hardcoded into the classes. But there are dynamic conditions such as being frozen, burning or poisoned that are hard to implement using this model. Basically adding and removing these features need to be solved in a custom way for each class that need them.

Regardless of these problems, the class based system worked relatively well for the first Grimrock, mainly because there was a relatively small set of object types and we knew pretty early what we needed. However, with Grimrock 2 we are planning to have a larger variety of objects and therefore we need to be able to quickly prototype new kinds of objects. With these requirements the class system begins to fall apart.

Luckily there is another kind of object model which has gotten pretty popular in game developer circles because it happens to solve all these problems neatly. It is the component based object system. With this system all objects are made of a number of components. Ideally each component implements a single thing and these things would not overlap. The components themselves are quite simple but the complexity arises when these components are combined. For example, the animated statue with sound would be made by combining Model, Animation and Sound components together.

For the past week I have been going through the existing classes in Grimrock and rewriting them with components (btw. this is one of the changes that would not have been possible if we were making a DLC). There is still work left but the codebase is already looking a lot cleaner. And we have already implemented some new objects, bridges over chasms to give you an example, that would have been messy to do with the old system.

To get some idea how the new component model looks like, you can find the definition of the new torch holder below. Notice how the torch holder does not contain any hardcoded elements. Components may also be enabled, disabled, added and removed dynamically from objects. For example, a single instance of torch_holder can be made temporarily silent by simply disabling its Sound component (or permanently by removing the component altogether).

    name = "torch_holder",
    components = {
            class = "Model",
            model = "assets/models/env/torch_holder.fbx",
            class = "Clickable",
            offset = vec(0.0, 1.4, -0.05),
            size = vec(0.35, 0.6, 0.35),
            debugDraw = true,
            class = "Socket",
            offset = vec(0.05, 1.53, -0.25),
            rotation = vec(0, -20, -90),
            onInsertItem = function(self, item)
                if == "torch" and self:count() == 0 then
                    if item:getFuel() > 0 then
                    return true
                return false
            onRemoveItem = function(self, item)
            debugDraw = true,
            class = "Particle",
            enabled = false,
            particleSystem = "torch",
            offset = vec(-0.015, 1.85, -0.4),
            class = "Light",
            enabled = false,
            range = 15,
            color = vec(1.3, 0.68, 0.35),
            brightness = 10,
            castShadow = true,
            shadowMapSize = 256,
            offset = vec(-0.015, 2.05, -0.45),
            onUpdate = function(self)
                local noise = math.noise(Time.currentTime() * 3 + 123) * 0.5 + 0.9
                self:setBrightness(noise * 10)
            class = "StaticShadowMap",
            class = "Sound",
            enabled = false,
            sound = "torch_burning",
    placement = "wall",
    editorIcon = 84,

18 responses to “Refactoring The Object System”

  1. Jack Dandy says:

    Good to be reading these again.

    I wonder just how flexible this will make the game engine for modders!..

  2. Rorrik says:

    Unless I’m mistaken, this will allow modders to make a far larger variety of objects than are present even in the game itself. Won’t they be able to mix and match components however they want?

    This is the direction I was drifting in my coding as well, I just couldn’t articulate why it seemed to work better. No that I understand it, I feel much more comfortable with the way I am compartmentalizing my database.

  3. LonePaladin says:

    I’ve seen a few roguelikes that use a system of item properties — the first two I can recall are Powder and IVAN. It’s been a while since I dug around the code on these, but this is what I can remember of it.

    An object gets assigned a material — a dagger might have ‘iron’, for instance. Somewhere else in the code is all the properties of iron: its weight per cubic foot; variables with names like CanBurn, CanMelt, CanFreeze; other numbers like a damage modifier, a color or texture file. You get the idea. There are all sorts of materials listed, with these properties figured out.

    Let’s say there’s a dagger on the floor when a fire spell goes off there. The spell has some sort of Heat variable; if that number is higher than the dagger’s CanMelt, it turns into a lump of the base material (you may have an option to pick this up and use it to make something else).

    This gives you the option of including effects that change an item’s base material. A dagger turned into wood can be used (briefly) as a torch. That granite statue too heavy to move? Change it to balsa. Is the party starving? Transmute some rocks into meat and chow down.

  4. Sirithang says:

    Love the component system, go for that each time I write some sort of engine. It’s both flexible, extensible and so easy to understand. Plus it’s oriented toward game designer/modder instead of being code/programmer centric.

    Just a question, at first glimpse thought your object definition was json (wat I use for my configuration/objetx files) but it’s more complex, what is it? LUA?

  5. Dhinanta says:

    I’m curious: Are you guys using an ECS you wrote yourselves? or one of those available around the internets, like Artemis?

    For those interested in understanding ECS (Entity-Component-System), there are dozens of useful links, but this one is a good summary of the “why” without getting into implementation:

    (Also, the little diagram helped me a lot initially)

  6. hannamarin says:

    When you have finished Grimrock 2 – will you go back and re-write Grimrock 1 to the later software version.

    Also will you make use of the map you created to link the different dungeons.
    Will you creating outside scenery and scenarios using the map as a base.

  7. Sharp says:

    Sweet solution indeed! Looking forward to see more objects and more “item possibilities” as LonePaladin said.

  8. sampy says:

    Good day, I am part of a group of guys who love this game.
    We read of a release of Legend of Grimrock for the iPad, but is not, has yet to go out? You tell us when we put on the market please.
    We all await your reply to buy Legend of Grimrock for IPAD!

  9. sohbet says:

    harika bi makale olmuş

  10. AdrTru says:

    this new system looks very god for making mods :).
    It will be possible to create more than 1 clicable/soket/particle in one object?
    Or change paramerets defined in object definition by lua? (changing vectors atc.)

  11. czychk says:

    you need to foundation your own seek about the type of vibram five fingers manufacturer’s concentrate on.

  12. degrade says:

    If you need to astonish ones lover along with ugg boots uk entertaining along with sexxy and then review your Kama Sutra array involving treats. Just about all superbly tied, these kind of primary reward ugg boots uk usually are anything that one could like far too. The actual Perfect Proverbial ugg boots uk may be a well-known preference.

  13. decy says:

    You will mainly find watches by the net where you can see a large variety of favored enjoy brands of created to fulfill everyone’s preferences & wishes.

  14. Xeniamamie says:


Leave a Reply