Ok, time to finish this small sample project. We won’t do anything too complex, but we’ll add something that the player would need to understand to solve at least one puzzle.

Let’s start adding a new room – the outside.

and then let’s add a south direction to go there from the living room – but with a difference, compared to the other movements.

Something that will show this thing:

Yes, we’re “trapped” in our own apartment!

To handle that we just need to use a variable, that needs to be set to a certain value to let us out.

A locked door means we need to find a key – that will add to normalobj – but stating that’s not “normal” – because it starts without attributes – and that means we won’t be able to see, or take it, even if we put it in the bedroom. It’s more or less a hidden object.

How should the player take it, if it’s not visible? Well, we’ll add a description for the bedside table, telling that it’s got a drawer. And then, if we check the drawer, we’ll let the player find the key – changing the object attributes.

That way, after examining the drawer, the key would be handled by our default take verb.

With that in our inventory, we just need to add handling for unlock

And here we go.

Then we can leave our home, and finish the game (actually, the game won’t stop – but there’s nothing more to do, if not moving back and read some other descriptions)

What do you think about that? Things are quite straightforward – even if of course that doesn’t mean you won’t find some difficulty, at least at the start, because of the syntax and/or because this starts to be “linear” only after some tests.

But the point is – yes – with this tool, it all but impossible to build a graphic text adventure for C64.

I’ll add (and possibly change) something here and there, trying to simplify things and improve the whole system, but if you’re curious / interested, consider saving a bookmark for this blog, for my github page, or for my itch.io page.

(the whole project is available here)

Before finishing this small sample adventure there’s a thing that may not be clear, and that I’ve decided to explain and handle better (I mean, changing the script compiler).

The point is: we defined an object (i.e. our bike), then we added a name property (“your bike“).

Doing that, we’ve told our engine not only to be aware of the existence of an object in our game but also how this object must be called when asked. Is that all? Nope. We’ve also implicitly told our engine how that object can be referenced by the user in the game. “take bike” can be handled, because bike is both the object name for the game engine AND the object name for the player.

I guess this can’t be immediately clear – so, to explain what I’m saying, let’s say we want to localize our little game, adding an Italian version. Of course, I could clone the whole script file, and localize everything in Italian (changing bike to bici, for instance). BUT I may want to have the same script, able to handle BOTH languages at the same time, just because I could want to improve/bugfix it in the future, without having to worry about syncing the two scripts.

To do so, I can split the object name, used by the engine, from the object name used by the player, adding a way to express a synonym property.

Doing so I can have ONE object name for the script part (bike – but I could have called it obj01 for what is worth) and a set of name, description AND synonyms for each language I want to handle.

bike will be used in the script to reference the object INSIDE the game script, while localized synonyms will handle user input.

Then, I just need to add a configuration property to state WHICH one I currently want to compile into our C64 program to have the resulting game. (No, I don’t want to have multilanguage selectable runtime – we’ve got really few kb of memory and I prefer using them for the game. I mean, we can distribute TWO different versions, simply doing two builds)

The last thing I still needed to do was to add also the ability to localize even the msg command. After that, we’re ready to go.

And now we can have this

or this

Simply changing the config parameter

A note: this new feature is NOT mandatory. If we DON’T specify a two-letter language before name, desc, msg or synonym we’ll simply got them used like before

Even in this now-bilingual sample I still have a not localized msg that’ll work in the same way as compiling the Italian or the English version of the game.

Before going on, as already anticipated, we’re going to remove the specific global verb handling and simply include the standard library.

That way we’re getting all the default behaviors – including the messages for unknown verbs.

Then let’s add an image for each room, just so that they look cooler.

But even if now these two locations look cooler, they’re still not good enough. Why so? Because, being this a graphical-text-adventure, we don’t want only (or mainly) graphics, but also text. We want to be able to interact, to explore the game locations, using verbs. So we need descriptions at least for some of the objects we mention (or that they’re supposed to be there).

To do that we need to add objects in the game script. But what kind of objects do we really need?

If you don’t even get the question, it’s fine. In the real world, objects are simply straight objects.

But in a game, some objects are more real than others.

The ones that are important for the game can probably be taken and moved around, while the ones that are just there to enrich a room perception, well, they are scenery. They just need a description. Or a few specific verb handling.

In the stdlib.hjt you’ll find some object classes. They can be changed or added, but they are just different for the attributes they’re assigning to their objects.

In our library scenery are the objects that are there, that you can check or interact with, but that you won’t see in the room objects list. sceneryobj are instead automatically “visible” in the room description in a special way. The normalobj have also a takeable flag that’s used by the get/take verb to know if it’s possible to put them inside your inventory.

Let’s add something to our rooms, so that’s easier to understand the differences between these three kinds of elements.

And let’s also add a “real” object – your cellphone – not tied to a specific room, even if starting in one specifically.

If we’ve something like that in the stdlib…

…entering in the living room we’ll get 1) the room description and 2) a list of listable objects – in this case our bike.

We can’t get it (so we’ll get the default message for this verb) but we can examine it. And we can of course examine also all the other local objects, even if they’re not so important for the game that we want them listed when you check the room.

The last thing I want to underline is the normal object – that’s to say our cellphone. A visible, listable, and takeable “global” object that we decide to put in the bedroom from the start.

So entering the bedroom we can see it, but we can also take it, and have it in our inventory.

And, well, if we want to do so, we can also drop it in the living room, adding this object to the listable ones there.

The game so far is minimal – but it starts to feel like a game, doesn’t it?

The only missing thing is at least a puzzle to solve. Something we need to figure out, to reach a goal.

Ok, let’s see how to go from one starting location with no interaction possible to something, still minimal, but playable.

Let’s start adding two rooms, a bedroom (with the game starts) and a living room.

For those two locations, we need to have at least a description, so let’s add it, this way:

• Please note that we can put the part after the : or inline or as text under the same node. In this case, we prefer to have a description, that’s longer, as text on the right, while we keep the name directly visible on the tree structure.
• And please note also that we don’t have msg: command in the description because that’s an attribute, and not “code”.

Let’s go on. Now we change the $start onfirst code so that after a simple initial message we’ll set the game starting point to the bedroom.

• as you can see there are two new commands: waitkey and goto:
• here we’ve used references to the config part (we already had name, now we’re going to add the other two elements)

With these changes we’ll get that:

And, after pressing a key, we’ll go there

That’s not what you expected, is it? why don’t we see any description – and we still have the previous text?

Because my engine doesn’t assume you want something in a specific way. It’s built to be as extendible as I thought it was wise (for a very small one, being designed to run on a 8bit computer)

So, we need to tell it what we want.

And that means that we need (and want) libraries of standard behaviors.

Instead of adding each behavior inside the game script, we can create a stdlibj.hjt (read that as “standard library.hjt”) and “include” it, of course knowing that we can change everything we want if we need it.

Ah, of course a standard “standard library” is provided on GitHub, so you don’t need to understand everything and build your own (for now).

But, let’s fix this thing in our sample game, before including that, so that you can understand better what’s under the hood.

To do so we need to add a verb section and define what we want to achieve for onfirst and onenter events.

We want to have the screen cleared (clear) we want to read the room description and if there are visible, listable objects in the room, we want to read their list.

Added that, we’ll see this:

That’s surely better, isn’t it?

But 1) we still can’t do anything and 2) you may ask: hey, but now we have TWO onfirst, why’s that?

About the 2) – yes, we got two of them. BUT, and this is quite important, we have TWO main level for everything. One is the global level (something that must exist or happen everywhere, with specific limits) and one is the local level (the room we’re in). So we can have a generic, global, verb handling, and an override, in a specific room.

And so, to move from one room to the other, we can choose the second level, and add a specific verb handling in each room, like that:

This way we can move from one room to the other.

BUT if I ask to move east from the living room, nothing happens, not even a message. And that’s why we need to add a global handling for movements – that simply say that we CANNOT move that way.

To do so we can add each verb where we put onfirst with a message, but my engine can do a bit better than that.

We can define classes – we can add a behavior – we can associate verbs to that class.

Like that:

And added that we’ll get this:

(Actually we get this after a small change – if we call a synonym set e|east we must refer everywhere else to that set using (only) the FIRST element. So we need to change the reference in bedroom and living room accordingly)

But, after that, we can move to and from the two rooms without problems. Still not a great game, but now we can interact.

As you probably DON’T know, I’m currently building a graphic-text-adventure engine for C64 – that’s called StoryTllrC64. The project (I mean, source code and staff) is under MIT license, and is currently on GitHub. I’ve already built and distributed two little games using it (Cloak of Darkness and Accuse) based on known, open-license games.

So, even if it’s still under development, it’s time to share some basic info about how to use it, in case someone may be interested in using it, once it’s completed (enough) to be used for a real game.

We are starting from a really minimal sample project.

Let’s start creating a folder for this sample.

We need to add some subfolders:

• bin, where the C64 game will be found after compiling
• png / img folders (for images, png and native)
• tmp, needed for temporary files during builds

And a couple of files:

• our main script file (let’s call it sample)
• a batch file, to speed up buildings

As you can see, the main script file has an odd extension (hjt) – that’s a TreepadLite file (and TreepadLite is a not-currently-supported-anymore program to create tree-like files). I’ll show you things using THIS program – but everything will be supported also using yaml files (text files with a specific indentation, to give you more or less the same tree-like features you can get with TreepadLite (anyway, this program, that was the free version of a commercial one, is still available around, so if you want you can still give it a try)

Anyway, what do we need a script file for? Well, to define the elements of our game and their interaction.

StoryTllrC64 uses at the moment only FOUR kinds of elements:

• verbs (they handle the game logic – you need verbs to make actions in your game)
• objects (based on characteristics they can be quite different, even actors are considered objects)
• rooms (places). A room is also the $inventory but also $nowhere or $everywhere
• variables (something that can be used to keep status, if it’s not related to objects)

To create a minimal game you must create at least ONE room – the one called $start – that usually is the “home page” of your game. The point from which you make the player go to your first real location, to enter the action.

But let’s start. After creating an empty sample.hjt if you double-click it you’ll see something like that.

Write “main” and add two sections – config (where your game info must be put) and room (the folder for your locations).

You don’t really have to create a configuration too – because defaults will be used otherwise – but it’s the place where you can define your adventure name, put your author name and specify other things (some important, some not). We won’t talk about that now.

We’ll simply add a name, and the $start place

Then we’ll add three other things:

• image, a reference to a 320×96 png that will be added to the game and shown in that location. We’ll used a shared one for this sample, but you can try with your own.
• onfirst, an event handler that will be called the FIRST time you enter that place during the game (there’s also an onenter handler, that’s called every time, but the first if you added also the onfirst)
• the FIRST “code” of your game – a sequence of messages that will be shown in the game

Once you’ve saved, you can run it and show the game inside your favorite emulator.

How can you run it? Using the batch file that will do a sequence of operations:

del *.h
del advcartridge
del make.bat
....\script_compiler\bin\script_compiler.exe sample.hjt
call make
bin\sampleadventure.d64

That’s to say:

• cleaning any previous generated file (*.h or advcartridge depending on the kind of build) including the batch file with the C64 disk creation using c1541 program, which will be created by the script_compiler, after it finished to compile your script, generating a binary file (or .h headers)
• running the script_compiler
• running the new generated make file to create the C64 disk
• running the C64 disk with your game

That’s what you will get:

In case you’re curious, in your folder now you’ll see some generated files:

You’ll see more in tmp and img folders (but you don’t need to care for them). In your bin folder there’s the only file relevant for you, that’s the one with your C64 game (the one launched by the batch file)

A note: the direct creation of a d64 file (based on the already-built engine provided on GitHub with also the script_compiler) is ONE of the choices you have – because (if your game has not too many images) you can also create a version of your game able to run on a tape (single file). But to do that you’ll need to rebuild the engine with CC65 (a C compiler for 8bit) including new header files generated by the compiler. This is surely more tricky – even if it’s the best way to redist your game (if it’s small enough).