RL Coding Tutorial with libtcod

[jonoerik]

Miko suggested this in the SSN thread, and I was wondering if there was any interest in the concept.

Basically; We (the libtcod community) write a tutorial on how to code a roguelike game.  The tutorial would be a collaborative effort, with each of us helping to write and refine both the code and instructions (wiki anyone?).  The tutorial would go through the steps involved in building a simple roguelike game.  Detailing how each game component is constructed, and how they all link together.  Don't forget lots of flow charts, diagrams, and screenshots!

The game would be simple in design, and traditionally roguelike, but would leave a lot of scope for customization, especially in the setting.  The mechanics of the game would revolve around fighting in a roguelike environment, but this environment could be High Fantasy, Modern, Cyberpunk, or whatever each individual wants.

I'm particularly fond of python as a coding language, and think that it would be a good language to write the tutorial in, as the code would be simple and easy to understand, while introducing various roguelike concepts.  There are many choices for language, so we will need to decide on one.

So... Anyone interested?

[Scautura]

Perhaps those who are capable could translate from one to the other - e.g. One person (you, for example) writes an example in Python, somebody else (donblas) writes a C# version, a third person (me) does a C++ implementation, etc... The benefits of a wiki mean that this sort of thing is (relatively) easy.

[jice]

There's a tutorial for python here :
http://kooneiform.wordpress.com/2009/03/29/241/

There's also a tutorial I started here but I won't keep working on it :
http://code.google.com/p/thecave/wiki/toc

it's very detailed but doesn't cover a whole roguelike, only a hello world... Moreover, it's for the canceled 1.5 so it should be downgraded to the 1.4 branch

[jonoerik]

I like the idea of writing it in multiple languages.  I'd be happy to try some sort of python translation once the original code is done.

That python tutorial is a good starting point, but doesn't seem to go into combat/inventory systems, or gameplay (or is that focused on in future parts).  I'd like this tutorial to focus on getting a complete (although simple) roguelike game together, not just the drawing and movement code.

[miko]

The http://kooneiform.wordpress.com/2009/03/29/241/ is actually what pointed me towards libtcod in the first place, and is a great resource.  I am not sure exactly what I have in mind, but when I do I will post it!

[george]

I have to agree (as the author of the kooneiform stuff  ) that it doesn't really go through any gameplay coding. Also if you follow the series from beginning to end it's probably not the most efficient tutorial, as I frequently refactored things as I went. That may be educational in itself for the beginner but probably not the best for a basic tutorial.

I'd be happy to contribute to a Python version though -- is anyone still working on this?

[miko]

I am not working on it now, but that is because I am still blundering along and figuring out the way things should work.  I enjoy working with a high level of encapsulation in an OO-approach, but it appears that this does slow down the performance.  I have taken a look at using Cython with libtcod and moving some of the essential classes (Cells and CellMaps) to built-in types in order to increase the performance... easy to get lost down that avenue!  So in short, I am still making the mistakes I hope to help others avoid and not writing it down.

[Jotaf]

The tutorial doesn't need to teach you the correct way to code RLs. Actually, it's quite the opposite: the better the coding standards, the more time consuming the process will be. If the tutorial is long and never gets to the juicy bits, such as zapping goblins, the would-be RLs will be lost in the way.

I propose we collab on the design guidelines for the tutorial, just so that it all makes sense before we start making an investment! Like this:

Code:

Title: My First RL!

Graphics: Single torch like in the demo, fog-of-war (so it feels like
you're actually exploring)

Levels: BSP generated dungeons so we can just use what libtcod already
has. Town level and shop a bit too much?

Stats: HP/Attack/Defense, for both the player and every monster. (I'm
sure this is one of those areas where a beginner would love to tinker
and it's pretty easy to add other stats.)

Items: Additive HP/Attack/Defense modifiers when worn. A string
determines its class. Can equip one item of every class (weapon, armor,
helmet...). Item screen with drop and use options (use equips/dequips
stuff). (Should be relatively easy in python at least, where list
support is awesome.)

Combat: Damage = Attack - Defense, or something. Would be cool to have
a special graphical effect tied to wands and staffs (which would just
be weapons with different names).

AI: Cast ray to player, if unblocked move towards, if near it, attack.

What do you think? Too ambitions?
I sure as hell would feel very accomplished as a newbie if I had a game like this with a few modifications according to my taste.

[jonoerik]

What do you think? Too ambitions?
I sure as hell would feel very accomplished as a newbie if I had a game like this with a few modifications according to my taste.

That looks pretty good.  Just don't let the map generation complicate the early tutorials too much.  While messing with bsp's to create intricate dungeons is certainly fun, we probably want to focus on getting a functional, playable game working on a simple map first.  My roguelikes seem to always finish with a good looking map, but nothing to do on it!  The full dungeon/forest/city system can come later.

Making use of OOP seems like a good idea, and would simplify the concepts involved.  I'm fairly busy getting my own C roguelike started, but I'd be happy to add to the project once it's started.  Even writing the actual text of the tutorials.  The hardest part will be getting the code started.  Also; if the tutorials are to be followed in order (and I can't imagine any other way of doing things), then we'll need to keep a version of each code corresponding to each tutorial.

[george]

I think that outline is good as long as we keep things simple. Stuff like graphical effects for magic are great in my opinion because they give you that cool feeling when you code it, even if it's just a type-in.

jonoerik, I suggest you edit the OP to start a list of people volunteering to do what. You can put me down for something in Python.

Does Jotaf's outline work for separating the tutorial into parts?

[Jotaf]

While messing with bsp's to create intricate dungeons is certainly fun, we probably want to focus on getting a functional, playable game working on a simple map first.

Fair enough! Even though libtcod's support for BSP maps is nice, it does need a fair amount of tinkering to generate a map with connecting tunnels and all.

Can someone suggest an easier algorithm?

I was thinking about something along the lines of this: try to place a bunch of rectangles, unless they overlap (use an image buffer as the map and libtcod's rectangle drawing function?). As they're placed, record their center coordinates in a list. Then connect each center to the next in turn. Choose randomly one of two hypothesis: draw a horizontal tunnel to the target's X coordinate and then a vertical tunnel to the Y coordinate; or first vertical and then horizontal. Again, libtcod's v/hline drawing functions could come in handy. The first center is the entry stair and the last is the exit. It doesn't matter if tunnels overlap or cross entire rooms if room and tunnel tiles are indistinguishable. This is intentionally simple, and I used it to code a RL in my TI calculator

Stuff like graphical effects for magic are great in my opinion because they give you that cool feeling when you code it, even if it's just a type-in.

I agree, even if it seems like useless fluff, a couple of features like this should amount to a fair deal of polish.

Does Jotaf's outline work for separating the tutorial into parts?

I didn't think about that when I put it together but it depends on whether one's willing to code/write a big part or a small part, so it should be up to the coder/writer. Also I'm not sure if this is the best ordering of the parts either.

[jonoerik]

Fair enough! Even though libtcod's support for BSP maps is nice, it does need a fair amount of tinkering to generate a map with connecting tunnels and all.

For the map generation; In my experience, simple outdoor environments can be much simpler to generate than dungeons, the base being a large walled square with some random trees/rocks.  The tutorial can go into BSPs for future additions, like buildings.  The problem here is that outdoor environments aren't as customizable in terms of setting, although I guess the large walled square doesn't have to be outside.

...code a RL in my TI calculator

A TI RL?  Nice!  Shame I had to sell my TI.  The Casio Classpad I've got now is nice (touchscreen ), but has no cursor addressing, so simple roguelikes aren't really possible.

[Jotaf]

For the map generation; In my experience, simple outdoor environments can be much simpler to generate than dungeons, the base being a large walled square with some random trees/rocks.  The tutorial can go into BSPs for future additions, like buildings.  The problem here is that outdoor environments aren't as customizable in terms of setting, although I guess the large walled square doesn't have to be outside.

Hm... I think that coding outdoor environments is not as rewarding. An important metagame within a RL is exploration of the labyrinth that is a dungeon. Even though I know the patterns that will be generated in my RL's dungeons, I still find a primal joy in uncovering it room by room.

Hey I'm feeling the urge to code right now. I think I'll code up the dungeon generator I described, based on the "@ with a lamp" demo. Don't worry, I won't lock the design; I'll focus on the dungeon generation only.

A TI RL?  Nice!  Shame I had to sell my TI.  The Casio Classpad I've got now is nice (touchscreen ), but has no cursor addressing, so simple roguelikes aren't really possible.

Well, the cure for that is making your own screen buffer and drawing it whole It was really fun but at the same time I think I got cramps from those tiny keys! And the programming interface is terrible; copy-and-paste is rudimentary and any edits are final (no undo, no saving)... A real geek adventure

[Jotaf]

Done. Here's the short version (everything else is just a bunch of 4-lines helper functions and classes). It's your standard rooms-and-tunnels dungeon, but with an algorithm designed to be simple and short.

Code:

def make_map():
global map, playerx, playery, stairsx, stairsy

#fill map with "blocked" tiles
map = [[ Tile(True)
for x in range(MAP_WIDTH) ]
for y in range(MAP_HEIGHT) ]

rooms = []
num_rooms = 0

for r in range(MAX_ROOMS):
#random width and height
w = libtcod.random_get_int(0, ROOM_MIN_SIZE, ROOM_MAX_SIZE)
h = libtcod.random_get_int(0, ROOM_MIN_SIZE, ROOM_MAX_SIZE)
#random position without going out of the boundaries of the map
x = libtcod.random_get_int(0, 0, MAP_WIDTH - w - 1)
y = libtcod.random_get_int(0, 0, MAP_HEIGHT - h - 1)

#"Rect" class makes rectangles easier to work with
new_room = Rect(x, y, w, h)

#run through the other rooms and see if they intersect with this one
failed = False
for other_room in rooms:
if new_room.intersect(other_room):
failed = True
continue

if not failed:
#this means there are no intersections, so this room is valid

#"paint" it to the map's tiles
draw_room(new_room)

#center coordinates of new room, will be useful later
(new_x, new_y) = new_room.center()

if num_rooms == 0:
#this is the first room, where the player starts at
playerx = new_x
playery = new_y
else:
#all rooms after the first:
#connect it to the previous room with a tunnel

#center coordinates of previous room
(prev_x, prev_y) = rooms[num_rooms-1].center()

#draw a coin (random number that is either 0 or 1)
if libtcod.random_get_int(0, 0, 1) == 1:
#first move horizontally, then vertically
draw_h_tunnel(prev_x, new_x, prev_y)
draw_v_tunnel(prev_y, new_y, new_x)
else:
#first move vertically, then horizontally
draw_v_tunnel(prev_y, new_y, prev_x)
draw_h_tunnel(prev_x, new_x, new_y)

#finally, append the new room to the list
rooms.append(new_room)
num_rooms += 1

#after that, place the stairs at the last room
stairsx = new_x
stairsy = new_y

The player is placed at the first room and the exit stairs at the last. I think the results are quite good for such a simple algorithm; also, it ensures full connectivity. I attached the full source, it's built on top of the FOV sample with almost no modification -- the important part is the dungeon generator after all. It's ready to go, just extract and double-click map_gen_tutorial.py!

[jonoerik]

Nice work Jotaf.
The code works well, although it didn't seem to exit straight away after reaching the door.
I'm not so sure about the reliance on those helper functions and classes, but thats probably the simplest way of going about things.
Keep up the good work, all!