Trystan's blog

My plan for the 2012 7DRL

2012-03-05T16:31:00.000-08:00

I've been thinking a lot about what I want to do with this year's 7DRL. For 2011 I wanted to see what it was like to not be the hero but have to cooperate with other heroes and to try a survival goal rather than the tried-and-true "descend and return". Even though it wan't very fun, I'm happy that I did that and I consider it a success. I've posted some of my ideas before, but as March approaches, I've been narrowing down what I want to focus on.

Event based architecture. I've had a lot of fun and learned much while delving into simple event based programming and I think this will be a good test of how to apply it to an interesting application. Roguelikes tend to have very messy dependancies and have an unholy number of exceptions to the rules and complex interactions so this will be a good test of how well I can make events, commands, and sagas work.

Interesting overworld. I've gotten tired of playing games that have too much uninteresting space. Long corridors, huge outdoor fields, empty room after empty room after empty room. I want small and unique spaces. Moving is so boring that some roguelikes have it automated for you. Despite all the hours I played the original Zelda as a kid I never got tired of it. Each screen had its own unique charm and character, each fit within its own little neighborhood, and each area had it's own secrets to reveal. I want that.

Random monsters. Other than the Forgotten Beasts of Dwarf Fortress, I haven't seen this implemented. I don't think I'll have DF's giant vomit monsters, just a few species with three or four random advantages each game. This should add variety like identifying potions does, except perhaps with deadlier consequences.

Dynamic quests. The more I think about it the less intimidating this seems - but that may just be my own hubris. Since it's a 7DRL I will probably only have a few quests. Getting other people to follow commands and attempt the same quests would be interesting - and it should be possible if I'm right about the connection between commands and quests.

Focusing on these means I would de-emphasize other things. There will probably be just a few simple armors, weapons, and other items. I will most likely skip magic alltogether. The game itself may not even be fun or difficult. I'm not sure what the story will be either but it should involve quests and followers. I should probably think of something soon otherwise I'll end up with just a proof of concept: a bunch of neat ideas with no theme to tie them together.

My 7 day plan:

Day 1. Hyrulian Overworld: worldgen, player controlled @
Day 2. Basic gameplay: basic creatures, basic combat, basic stats, basic items
Day 3. Monsters: randomized monsters, better creature AI, a few status effects
Day 4. Society: people, victory, basic commands
Day 5. Dynamic quests
Day 6. More content and polish....
Day 7. More content and polish....

Followers, spoken commands, and quests

2012-02-28T08:24:00.000-08:00

I think I've found something that hasn't been done that could add a lot to roguelikes: spoken commands. You type what you want your followers to do and they do it. Instead of having a complex AI that handles the entire english language, you could focus on a few things that could be combined in different ways. If you have many people following these commands then you and your rag-tag team of adventurers could really change the world.

Here's a simple command syntax that I have in mind:

<target> <verb> [<objects>] [<preposition clauses>]

target is an optional person or group you are talking to: healer, fighters, Bob, Joe, etc.

verb is one of a dozen or so supported verbs: attack, defend, go, pickup, drop, help, etc.

objects are the people, places, or things directly involved with the verb: a sword, goblins, me, the desert, home, etc.

preposition clauses are optional clauses that constrain the verb: in <location>, with <item>, etc.

The prepositions are where the real flexibility and power come from since you can specify where something should happen, what should be used, or whatever else makes sense. The verbs, people, places, things, and prepositions would be whatever is appropriate to the game; resource gathering, squad maneuvers, mixing potions, social intrigue, whatever you can think of.

Turning the spoken words into commands would be three steps:

Normalize the sentence, removing fluff words and changing synonyms (protect -> defend)
Parse the sentence
Correct the prepositions and objects if necessary

As an example, Miners, give the blacksmith ore from the mines would be normalized into

miners give blacksmith ore from mines which would be parsed into this:

target = miners

verb = give

objects = blacksmith, ore

prepositions = from mines

The correction phase would be necessary in this example since the "give" verb requires the verb's object to be a thing and requires a "to <person>" prepositional clause. "blacksmith" is a person and "ore" is a thing so "blacksmith" should be the "to" prepositional clause and "ore" should remain as the verb's object. The corrected interpretation is:

target = miners

verb = give

objects = ore

prepositions = from mines, to blacksmith

or miners give ore from mines to blacksmith

So the miners who hear this would get ore from the mines and give it to the blacksmith.

Some other example commands:

healer, help the villagers at home

kill the goblins in the dark forest with spears

Urist, craft a sword with steel at the master's forge

guards, escort the prince from the castle to the fort

There seems to be a deep similarity between commands and quests. Even my example Lost Heirloom Quest could be seen as a command: player, give the McUrist family watch from the dark forest to Urist McUrist. Since the NPCs can follow commands, and commands and quests are the same, then they should be able to follow quests. Also; since the player can give commands, the player is also giving quests. Imagine a world with a few hundred NPCs running around trying to fulfill quests and giving quests to others when appropriate.

Procedural quests for a dynamic world

2012-02-22T20:38:00.000-08:00

Interesting and procedurally generated quests are something of a holy grail for many roguelike developers. I've also given it some thought and here's a simple idea I came up with.

Basically, if you have a catalogue of possible quests and you have an event based architecture, then each quest type would have it's own saga. That saga would listen to domain events and when the preconditions were right, it would add the quest to a quest giver. By talking to a quest giver the player, or any other actor, could accept the quest. When the saga receives the right domain event, the quest is over and everyone undertaking the event is rewarded or notified as appropriate.

Here's a concrete example I'll call a Lost Heirloom quest.

A LostHeirloomSaga subscribes to certain events like PersonMoved (while fleeing or confused) or ItemStolenFromPerson. As a response to those events, it may create a LoseItem command with a reference to the person and item.
Some command handler causes the target of the LoseItem command to drop the item (if it wasn't already stolen) and create an ItemLost event with references to the person, the location, the time, the item, and the reason why.
The LostHeirloomSaga listens to ItemLost events and when it handles the event, the person who dropped the item is given a LostHeirloomQuest and can ask others to accept it.
When the player talks to that person they can accept that quest. The details from the LostItem event can be used to create the quest specific rewards and text. Imagine talking to URIST McURIST the WOODCUTTER when he says "TWO WEEKS ago I was CUTTING WOOD in the DARK FOREST and was attacked by a GIANT BEETLE. While fleeing for my life, I dropped my McURIST FAMLIY WATCH. If you find it and return it, I'll give you my spare WOODCUTTER'S AXE and a PASS TO THE WOODCUTTER'S GUILD."
The LostHeirloomSaga also listens to ItemGiven events. When the item that was given matches a lost item and the person it was given to matches the person who lost it, the associated quest is completed and the person who gave the item is rewarded.
If a CreatureDied event for the quest giver happened, an ItemDestroyed event for the lost item, or some other quest-canceling event happens, then the LostHeirloomSaga cancels that creature's quest and everything else is cleaned up appropriately.
For extra awesomeness, when the saga notices other events related to the item (like ItemSold or ItemPickedUp), it could somehow add details to the world about it. Maybe the town's gossipmonger would tell you rumors about how the local blacksmith found a family watch in the dark forest. You could then talk to the blacksmith to find out what happened to it or you could sneak through his stuff when he's not looking.

Implementing this quest means adding a few classes: a LoseItem command, a method to handle that command, a ItemLost event, a LostHeirloomQuest, and a LostHeirloomSaga. The neat thing is that no existing classes need to be updated except for making sure the quest saga subscribes to the right events - all the logic is contained in the command handler and LostHeirloomSaga. The LostHeirloomSaga can use details of the quest giver to create dynamic and relevant details about what was lost, how it was lost, and when and where it was lost as well as a reward appropriate for the quest giver and the location and value of the lost item.

The real emergent behavior comes from quests that play off of events generated by other quests. If each quest can be ended two or three different ways, each quest directly or indirectly involves affecting the world, and there are multiple actors giving or accepting quests, then a complex chain of events could cause gathering firewood to lead to the downfall of a civilization.

Perhaps LostHeirloomQuestCompleted events please the god of compassion who may give the quest completer a Help The Townfolk quest.
Perhaps when a Rescue Princess quest is ended by the princess dying, her family creates a Kill Person quest targeting the killer and a Revenge quest against every group the killer was a member of. When a Rescue Princess quest is ended by the princess returning home, her family rewards whoever escorted her and every group the escort is a member of.
Perhaps 10 Expand Influence quests must be completed before a size 3 town can become size 4. Whenever an Expand Influence quest is completed, nearby paranoid town mayors become nervous and may create an Attack Town quest or Assassinate Ruler quest targeting their rival neighbors. When an Attack Town quest is completed, the targeted town's mayor can give Strengthen Defenses and retaliatory Attack Town quests. Undertaking either requires buying resources from the market and if a market trader's goods are running low then he could create Gather Resource quests. Of course gathering resources in your neighbor's territory will cause them to hand out quests to get you to stop; by bribery, trade, or sword and shield.

This, right now, is just idle speculation but I think this could be done. By relying on domain events and sagas, new quests can be implemented without muddying up the existing code since it doesn't even need to be touched. By relying on specific details of the people and places creating the events, compelling and believable quests can be generated. And by relying on quests that build on domain events raised as part of attempting other quests, an interdependent and dynamic history following simple laws of cause and effect can be created. I'll have to create a proof of concept some time.

Procedurally generated puzzles

2012-02-16T10:33:00.000-08:00

Just jotting down some informal thoughts on types of puzzles and how to proceduraly generate them. Each puzzle is really a barrier that you must overcome to get to the other side. Place a puzzle when you need a barrier to seperate zones, protect treasure, or just to keep things interesting.

Minigames. Reminds me of the Wii party games where whichever team gets the best overall score after 5 events wins the tournament. Slider puzzles, tower of hanoi, checkers, gambling, etc. It would take time to code each one but it would also break up the monotony. You could also make the real game a metagame of the minigames. Imagine everyone in the game is obsessed with a collectable card game. By finding new cards in the game world you improve your chances of winning the card minigame, which could lead to rewards that improve your chances of the real game. Done right it would be interesting and fun diversion; done wrongly it would be a tedious and required waste of time.

(days later) I just remembered that Star Wars: Knights Of The Old Republic had this with Pazaak! I was thinking more along the lines of a Magic The Gathering type minigame, but a poker-blackjack hybrid is a good idea too. Neat! Proof that my idea works!

Logic mazes. Reminds me of many games where you have to move like a knight on a giant chess board or slide across the ice in just the right pattern to make it to the other side. For these puzzles you must go from here to there but you must follow a certain way of moving. I think these would be easier to make in reverse. For example, start with an impassible expanse of ice. Start at the end point. Pick a direction and place a block in that neighboring cell. Move the opposite direction a few spaces. Repeat several times, making sure not to place blocks in areas the player will need to later pass through, and you end up with an end point, a start point, and at least one way to move from the start to the end. There are many more examples of logic mazes at http://www.mazelog.com/.

Inventory based. Reminds me of Metroidvania games. You must have a certain item or ability in order to pass. A locked door requires a key, a hall of spikes requires the spike armor, cracked walls require bombs. Basically there's some sort of "lock" and some sort of inventory "key" is required to pass. To place an inventory based puzzle, simply pick something from a preset table of a "lock" and item "key" and place the key somewhere before the lock. Or pick a random item from the world as the key: "The burly guard won't let you pass until you give him A HAM SANDWICH."

Knowledge based. Reminds me of Myst. You must answer a question or enter the correct sequence to pass. A combination lock where the randomized combination is written down elsewhere or a guard who asks you questions that you would only know from reading books in the game or talking to people in the game. Like the inventory puzzles, simply pick something from a preset table of a "lock" and an information "key" and place the randomly generated key somewhere before the lock.

Environment based. Reminds me of many sub puzzles in modern Zelda games. You must change the environment to a certain state before you can pass. Pull the lever to open a door, push all 4 buttons to lower the bridge, set all 6 torches on fire to open the treasure chest, redirect the laser to destroy the statue. This could be a superset of sokoban puzzles which are really just "push the blocks into the marked places". If you look at it a certain way, the requirements or triggers could even involve other people or groups: the king must be dead, the mages guild must be at war with the fighters guild, the price of milk must be low, the senate must be mostly of the Merchant's Alliance, etc.

These puzzles can be combined to form larger and more intricate puzzles:

To get the treasure chest you must push all four buttons

to push button 1 you just walk over and push it
to push button 2 you must cross a bottomless pit

to cross the pit you must purchace Flying Boots or know how to teleport

to push button 3 you must open the giant door

to open the door you must find and reassemble the 2 gears to the door machinery

gear 1 is on the other side of a giant randomized sokoban puzzle
gear 2 is buried at a random location

shovels can be purchaced at stores
the location is on a map you find in the dungeon

reassembling the gears is a slider puzzle

to push button 4 you must defeat the guardian with a special sword and a special shield

to get the special sword you must help the dying king

the king will give you the sword if you give him an elixer of life that no one knows how to make

the recipe is randomly generated but written in a recipie book - or you could just start mixing things and get lucky

to get the special shield you must play the specific melody on the piano

the notes of the randomized melody are written on the wall of another room

You could create a puzzle like this at each dungeon or important location or create one giant puzzle that includes all the major locations in the game world.

Ideas like this aren't worth much unless actually implemented though. I'll have to create some proof of concept or even a roguelike that has puzzles like this in it. One of these days.

Problems, solutions, and sandwiches

2012-02-11T10:32:00.000-08:00

Let's say you have a screwdriver and you happen upon a loose screw that needs to be tightened. Using the screwdriver to fix the loose screw seems like a pretty good idea - and it probably is.

Now you happen to have a loose nail that needs to be fixed. You know you should use a hammer, but if you're really lazy, don't have enough time to fetch a hammer, or if someone else insists on it, then you could probably bang the nail in with your screwdriver. Yes, it won't work as well as a hammer, you may damage the screwdriver, and you may hurt yourself, but at the end of the day you will have fixed the loose nail. You can then go home with a banged up screwdriver and sore hand and wish you could do it the right way. Not ideal, but it happens from time to time.

Now you happen to have an empty stomach. You really should eat a sandwich but instead you reach for your screwdriver. Why? Maybe everyone keeps talking about using a screwdriver so you go along. Maybe someone doesn't realize that even though sandwich and screwdriver have many letters in common, they're not the same. Or maybe you happen to have the screwdriver in your hand and really think it can help. For whatever reason, you, or someone else, decides that eating your screwdriver is a perfectly acceptable way to fix your empty stomach. Despite your best efforts and after several days or weeks, the best you can hope for is a broken screwdriver and several broken teeth. And you still have an empty stomach.

This may or may not be a thinly disguised allegory for certain events that may or may not happen when programming on projects that involve several other people and hard deadlines. This has been one of the most difficult things for me to deal with.

A possible algorithm for Zeldalike overworlds

2012-02-10T03:18:00.000-08:00

The 2012 7DRL challenge is one month away!

I've been thinking about how to procedurally create a Zeldalike map for a roguelike. By Zeldalike I mean the important parts that I remember from playing the original Zelda game: it was broken into screen-sized chunks, everywhere was reachable (although sometimes you had to get an item first), there were different themed areas, it wasn't too dense or too sparse - it was interesting, charming, and fun.

Here's an algorithm that should come up with something interesting like Zelda's overworld Hyrule. It creates one array of tiles and one array with details about each screen-sized chunk of the world.

Since the world will be broken into screen sized chunks, we can start by determining how those screens will be connected. Let's start with a 16x5 array of screens that have no connections to any neighbors. This is a high-level view of the world. If you were to print it out, it may look something like this where each screen is represented as a blank space and the walls between them are solid spaces.	################################# # # # # # # # # # # # # # # # # # ################################# # # # # # # # # # # # # # # # # # ################################# # # # # # # # # # # # # # # # # # ################################# # # # # # # # # # # # # # # # # # ################################# # # # # # # # # # # # # # # # # # #################################
With the array of screens, create a simple perfect maze. When printing out how the screens are connected to make a big maze, it would look something like this. We can see that this time, the top left screen has an open path to the screen to the east. After traveling east a few screens, you can go south.	################################# # # # ####### ### ##### ############### # # # # # # # ### # # ######### # ### ### # # # # # # # # # # # ### # # ####### ### # ##### # # # # # # # # # # # # # # ##### # # ############# # # # # # # # # # # # #################################
Remove some of the walls to connect screens. There are now loops and many ways to move around. Now when traveling east from the top left screen you can go south on the second screen or continue to the fourth screen and go south.	################################# # # # ### ### ### ##### # # ########### # # # # # ### # # ######### # ### ### # # # # # # # # # # ### # # ####### ### # ##### # # # # # # # # # # # # # # ##### # # ############# # # # # # # # # # # # #################################
Assign themes to some of the screens. I'm just using 1 through 5 as arbitrary themes. They could be like the original zelda: brown rock, green rock, brown forest, green forest, cemetary, etc or they could be your own themes.	################################# # 1 # 2 3 # ### ### ### ##### # # ########### # 4# 4 # # # ### # # ######### # ### ### # # # # # 1# # # # # ### # # ####### ### # ##### # # # # #5# 3 5# # 2# # # # # # ##### # # ############# # # # # # # # # # # # #################################
Spread the themes to adjacent screens that are connected.	################################# #1 1 1 4#2 2 3 3 # ### ### ### ##### # # ########### # 1 4 4# 2 4 4 # # # ### # # ######### # ### ### # # # # 5 #3 1# # # # # ### # # ####### ### # ##### # # # # #5# 3 3 5# # 2 2# # # # # # ##### # # ############# # # # # # # # # # # # #################################
Continue spreading them until all screens have a theme. This ensures that the themes match the path that the player has to walk through and the user should feel like they spend some time in each theme before entering a different one.	################################# #1 1 1 4#2 2 3 3 3 3 3 3 3 3 3 3# ### ### ### ##### # # ########### #1 1 4 4#2 2 4 4 4 4 4 2 2 2 2 2# # # ### # # ######### # ### ### # #1#1#5 5 5 2 2 2#3 1#4#2 2 2 2#2# # ### # # ####### ### # ##### # # #1#5 5#5#5 3 3 3 3 5#4#2 2 2#2#2# # # # ##### # # ############# # # #1#5#5 5#3 3#3#3 3 3 3 3 3 3#2#2# #################################

#####################&&&&&&&********* # ## ## #& &* ** # 1 ## 1 ## 1 #& 4 &* 2 ** # ## ## #& &* #####################&&&&&&&***** ##############&&&&&&&&&&&&&&******* # ## #& && &* ** # 1 ## 1 #& 4 && 4 &* 2 ** # ## #& && &* ##############&&&&&&&&&&&&&&******* ##############%%%%%%%%%%%%%%%%%%%%%%% # ## #% %% %% %% # 1 ## 1 #% 5 %% 5 %% 5 %% # ## #% %% %% %% ##############%%%%%%%%%%%%%%%%%%%%%%% #######%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% # #% %% %% %% %%	Now we can build the real world map based on the array of screens created in the earlier part. For each cell in the array of screens, plop down a screen sized chunk in the world array. For this example I'll make each screen 7x5 tiles large and just show the top left few screens but a real game would have much larger screens. I will also put the theme number and use different border tiles for each theme.
#####################&&&&&&&********* # ## ## #& &* ** # 1 1 1 4 &* 2 # ## ## #& &* ########## ##########&&& &&&***** ########## ###&&&&&&&&&& &&&******* # ## #& && &* ** # 1 1 4 4 &* 2 # ## #& && &* ### ###### ###&&&&&&&&&& &&&* ***** ### ###### ###%%%%%%%%%% %%%%%% %%%%% # ## #% %% %% %% # 1 ## 1 #% 5 5 5 # ## #% %% %% %% ### ##########%%% %%%%%% %%%%%% %%%%% ### ###%%%%%%%%%% %%%%%% %%%%%% %%%%% # #% %% %% %% %%	Then remove the walls for screens that should be connected. It would be easiest to always remove the one or two center blocks from a wall that separates connected screens but you could also make a wider path, a path at a different spot, or multiple paths between two screens. That would add variety but the screens are too small to do that here. After this, we have a themed maze to walk around in based on the array of screens.
#####################&&&&&&&********* # ## ### ##& & & &* $ $ ** # $ # # &* # ## ### ##& & & &* $ $ ########## ##########&&& &&&***** ########## ###&&&&&&&&&& &&&******* ######## #& &&# #&* ** ### &&& ? &* ### #### #& &&# #&* ### ###### ###&&&&&&&&&& &&&* *** ### ###### ###%%%%%%%%%% %%%%%% %%%%% ## #### ##%% %%% %% %% # # ### ##% * ! ## ####!$!##%% %%% %% %% ### ##########%%% %%%%%% %%%%%% %%%%% ### ###%%%%%%%%%% %%%%%% %%%%%% %%%%% #% %#%%%%%%%% %% %% %%	Randomly select different things to fill the screens with based on its theme: a center lake, small blocks of rock, rows of tree's, bordering trees, statues, etc. You could also have special things that only appear at dead ends: temples, towns, caves, treasure, bosses, puzzles, etc. Putting things at the dead ends makes it worth the time spent getting there - a good idea since most players hate dead ends and mazes in general. Secret areas and bad guys could also be placed now.
#####################&&&&&&&********* # ## ### ##& & & &* $ $ ** # $ # # &* # ## ### ##& & ~~~~~~ $ ########## ##########&&& ~~~~~~** ########## ###&&&&&&&&&& ~~~~~~** ######## #& &&# ~~~~~~ ~~# &&& ? &* ~~# #### #& &&# #&* ~~# ###### ###&&&&&&&&&& &&&* *** ~~# ###### ###%%%%%%%%%% %%%%%% %%%%% ~~ #### ##%% %%% %% %% ~~ # ### ##% * ! ~~ ####!$!##%% %%% %% %% ~~# ##########%%% %%%%%% %%%%%% %%%%% ~~# ###%%%%%%%%%% %%%%%% %%%%%% %%%%% ~~ %#%%%%%%%% %% %% %%	Hyrule had shore lines along some the edges and small lakes at the corner of four screens. You can add those too.
#####################&&&&&&&********* # ## ### ##& & & &* $ $ ** # $ # # &* # ## ### ##& & ~~~~~~ $ ########## ##########&&& ~~~~~~** ########## ###&&&&&&&&&& ~~~~~~** ######## #& &&# ~~~~~~ ~~# &&& ? ~&* ~~# #### #& &&# ~&* ~~# ###### ###&&&&&&&&&& &~&* ***** ~~# ###### ###%%%%%%%%%% %~%%%% %%%%% ~~~=~~~~~~=~~~~~~~~~~~~~=~~%% %% ~~ ### ##% * * ! ~~ ####!$!##%% %%% %% %% ~~# ##########%%% %%%%%% %%%%%% %%%%% ~~# ###%%%%%%%%%% %%%%%% %%%%%% %%%%% ~~ %#%%%%%%%% %% %% %%	Rivers could connect some of the lakes to the edges. It would be necessary to place bridges if the river is cutting off a path that used to be passable. A final step could involve looking at each screen or tile in the world and placing more treasure, creatures, or structures at interesting points.

I haven't implemented this yet so I'm not sure if this will really work or not. I'm also not sure how difficult this will be or how fun the results will be. It's something I haven't seen in any roguelike or non-Zelda game and if each screen has something interesting then it should avoid having long spans of time where all you do is walk around. I will probably use this for my entry into the 2012 7DRL challenge.

2011 7DRL re-retrospective

2012-02-01T12:28:00.000-08:00

I'm really looking forward to the 2012 7DRL next month and I've got a lot of ideas I want to try out. I rechecked the scores I got for my entry last year to see when I should focus this time. I'm quite happy with the scores for my 2011 entry but I think I can do better this time.

Here's what my 2011 entry Twelve Hours got:

Completeness: Bug free, polished game with no features that feel like they are missing.
2.67 - My highest score. I've got a much better idea of what I want this time, some ways of reducing memory and CPU usage, and some time set aside to add polish so I expect to get a 2.67 or 3.00 this time.

Aesthetics: Good looking, excellent controls and UI.
2.33 - A pretty good score; probably from the clean UI, few commands, and standard ASCII visuals. Less garish colors and a few small animations should help improve the aesthetics.

Fun: If you try any 7DRLs, try this one.
2.33 - One reviewer said: "Would be nice to have better control over your companions."Yup. I want to avoid having total control but I agree that more influence and interaction with others could add much more fun. Adding some humor and a more heroic feel won't hurt either. A 3.00 would be nearly impossible but I hope I could get a 2.67.

Innovation: Brings something fundamentally new to roguelikes.
2.00 - Reviewer: "Survive timer, goal other than finding the powerful artifact, inventory-less." My lowest score. I don't know about "fundamentally new" but I've got a few new ideas up my sleeve this year....

Scope: Beyond what you think could have been done in seven days.
2.33 - Fair enough. I was unfocused for the first few days so it was less than 7 days of useful work. I've got a long list of ideas in my head this time so I hope to have much more in the game this year.

Roguelike: 3 means Roguelike, 2 means Roguelike-like, 1 means Not Roguelike.
2.67 - "misses some points for tactical polish." Agreed. I've got some ideas and expect a 3.00 this time.

Average

2.39 - Not a bad score - not bad at all. I did better than I thought I would but this year I'd like at least a 2.50. By looking at last year's entries, this seems to be a very difficult and rare thing. On the other hand, if one reviewer had given me one more point my average would have been 2.59 so I think 2.50 is reasonable for 2012.

I think most of my posts for February and March will be about roguelikes. Ideas, implementations, and random musings and rants.

Java multimethods for a simple command handler

2012-02-01T11:03:00.000-08:00

I came up with a simple way to have an event handler easily handle multiple types. It's basically a way to say a class implements Handle<DomainEvent1>, Handle<DomainEvent2>, which works fine in C# but doesn't work in java due to type erasure. My solution: reflection based multiple dispatch. I'm sure others have done this before so it's nothing new.

public abstract class Handler {

 public void handle(Object message) {
  multipleDispatch(message);
 }

 private void multipleDispatch(Object message) {
  try {
   this.getClass().getMethod("handle", message.getClass()).invoke(this, message);
  } catch (IllegalArgumentException e) {
   e.printStackTrace();
  } catch (SecurityException e) {
   e.printStackTrace();
  } catch (IllegalAccessException e) {
   e.printStackTrace();
  } catch (InvocationTargetException e) {
   e.printStackTrace();
  } catch (NoSuchMethodException e) {
   ;
  }
 }
}

Not a good idea for high-performance applications and possibly not a good idea for any app. When you send a message to a class that extends Handler then the correct method will get called if it is capable of handling it. If you use a specific type then the specific method is called like normal, otherwise this multiple dispatcher tries to call the correct method.

System.Collections.IEnumerable and collection initializer syntax

2012-01-27T14:01:00.000-08:00

I'd like to make a post about something that I think is one of the least utilized aspects of C#: custom collection initializers. Implementing a custom collection initializer for your class can make your code much more declarative and concise.

It's common to have a collection of things that you set up at design time: drop down list items, configurations, items in a game, a list of mappings, all kinds of things. These are often stored in external xml files or in a sql table. If you're like me then you'd rather have this in code and have it as concise and easy to get right as possible. Here's how.

Look at this example of setting up a list of Armor types for a game:

public List<Armor> ArmorsWithListExample()
{
 List<Armor> armors = new List<Armor>();
 armors.Add(new Armor("leather armor",  1,  250, 10));
 armors.Add(new Armor("chain mail",     4,  500, 14));
 armors.Add(new Armor("splint mail",    7,  750, 16));
 armors.Add(new Armor("plate armor",   10, 1000, 18));
 return armors;
}

Here is the same thing using the collection initializer syntax:

public List<Armor> ArmorsWithInitializedListExample()
{
 return new List<Armor>() {
  new Armor("leather armor",  1,  250, 10),
  new Armor("chain mail",     4,  500, 14),
  new Armor("splint mail",    7,  750, 16),
  new Armor("plate armor",   10, 1000, 18),
 };
}

There are several advantages with the collection initializer syntax. You don't have to have the temporary variable, it's less code with fewer redundancies, and it's a nice declarative way to show that all you are doing is creating the collection. Small advantages, I admit, but they add up. But if you look at some C code, you see that the code can be even more concise by declaring the objects themselves inline. Here's an example from the game Brogue:

const itemTable armorTable[NUMBER_ARMOR_KINDS] = {
 {"leather armor", "", "", 10, 250,  10, {30,30,0},  true, false, "This lightweight armor offers basic protection."},
 {"scale mail",  "", "", 10, 350,  12, {40,40,0},  true, false, "Bronze scales cover the surface of treated leather, offering greater protection than plain leather with minimal additional weight."},
 {"chain mail",  "", "", 10, 500,  13, {50,50,0},  true, false, "Interlocking metal links make for a tough but flexible suit of armor."},
 {"banded mail",  "", "", 10, 800,  15, {70,70,0},  true, false, "Overlapping strips of metal horizontally encircle a chain mail base, offering an additional layer of protection at the cost of greater weight."},
 {"splint mail",  "", "", 10, 1000,  17, {90,90,0},  true, false, "Thick plates of metal are embedded into a chain mail base, providing the wearer with substantial protection."},
 {"plate armor",  "", "", 10, 1300,  19, {120,120,0}, true, false, "Emormous plates of metal are joined together into a suit that provides unmatched protection to any adventurer strong enough to bear its staggering weight."}
};

It's a small improvement but I want to do that in C# as well. With custom collection initializers, you can.

public List<Armor> ArmorsWithCustomInitializerExample()
{
 return new ArmorCollection() {
  { "leather armor",  1,  250, 10 },
  { "chain mail",     4,  500, 14 },
  { "splint mail",    7,  750, 16 },
  { "plate armor",   10, 1000, 18 },
 }.List;
}

Look at that! Concise and easy to get right. Here's the code for the ArmorCollection; notice that it's just a wrapper around a List. The only additional functionality it has is the Add method.

class ArmorCollection : IEnumerable
{
 public List<Armor> List { get; set; }
 
 public ArmorCollection()
 {
  List = new List<Armor>();
 }
  
 IEnumerator IEnumerable.GetEnumerator(){
  return List.GetEnumerator();
 }
  
 public void Add(string name, int weight, int cost, int ac)
 {
  List.Add(new Armor(name, weight, cost, ac));
 }
}

The Add method is what makes it work. According to section 7.6.10.3 of the C# specs, if a class implements the IEnumerable interface then the compiler converts the initializer syntax into a series of calls to the Add method, even though the Add method isn't part of the IEnumerable interface. The Add method can have any number of parameters and the compiler will make it work.

So when you have a collection of things that isn't going to change, instead of using a built-in collection with a series of Add calls, loading from an external xml file, or loading a sql table, consider creating an in memory collection by using a custom initializer: it may be easier, faster, and more concise than the alternatives.

My summary of CQRS and DDD

2012-01-24T17:00:00.000-08:00

Recent epiphany: sagas are just ways to turn domain events into commands.

Here's my as-of-now summary of the concepts I see in many EventSourcing, CQRS, and DDD videos and blog posts.

Command: A simple message that represents a user's request to make something happen. Just data with no behavior and often named in the imperative tense.

class CloseAccount implements Command
{
  public AccountId accountId;
  public String reason;
 
  public CloseAccount(AccountId accountId, String reason){
    this.accountId = accountId;
    this.reason = reason;
  }
}

CommandHandler: A domain service that turns a command into events by calling methods on an aggregate root, publishes the resulting events, and handles transactions and persistence. Stateless with just behavior; just a task based method and sort of procedural.

class AccountCommandHandler extends CommandHandler
{
  private AccountRepository _repository;
  private MessageBus _messageBus;
 
  public AccountCommandHandler(AccountRepository repository, MessageBus messageBus){
    this._repository = repository;
    this._messageBus = messageBus;
  }
 
  public void handle(CloseAccount command){
    Account account = _repository.get(command.accountId);

    account.close(command.reason);
  
    persistAndPublishEvents(account);
  }
}

Aggregate Root: A persistent domain object that turns method calls into domain events. May contain references to other domain objects as part of a parent/child relationship. Stateful and behaviorful and guaranteed to be internally consistent.

class Account extends Aggregate
{
  private AccountId id;

  public Account(AccountId id){
    this.id = id;
    super.storeEvent(new AccountCreated(this.id));
  }

  public void Close(CloseReason reason){
    super.storeEvent(new AccountClosed(this.id, reason));
  }
}

Domain Event: A simple message that represents a change to the state of an aggregate. Just data with no behavior and often named in the past tense.

class ClosedAccount implements DomainEvent
{
  public AccountId id;
 
  public ClosedAccount(AccountId id){
    this.id = id;
  }
}

MessageBus: A mechanism for publishing commands and events and subscribing handlers to commands and events. May be a separate EventBus and CommandBus. The only behavior is publishing events and subscribing event and command handlers to events; the only state is what's required to track which services have subscribed to which events.

public class SimplestEventBus implements EventBus
{
  private List<Handler> handlers = new ArrayList<Handler>();
  
  public void subscribe(Handler handler)
  {
    handlers.add(handler);
  }
  
  public void publish(DomainEvent event)
  {
    for (Handler handler : handlers)
      handler.handle(event);
  }
}

Saga: A persistent object that turns domain events into commands. Stateful and behaviorful. The only state is what's required for knowing when to create the commands.

// Send a notice to the account's owner once the account is
// both paid off and closed. (ignore thread safety since this is a simple example)
class OwnerNotificationSaga implements Saga
{
  private AccountRepository _repository;
  private MessageBus _messageBus;
 
  private List<Account> closedAccounts = new ArrayList<Account>();
  private List<Account> paidOffAccounts = new ArrayList<Account>();
 
  public OwnerNotificationSaga(AccountRepository repository, MessageBus messageBus){
    this._repository = repository;
    this._messageBus = messageBus;
  }
 
  public void handle(ClosedAccount event){
    Account account = _repository.get(event.accountId);
  
    if (closedAccounts.contains(account))
      return;
  
    if (paidOffAccounts.contains(account)){
      sendNotice(account);
      paidOffAccounts.remove(account);
    } else {
      closedAccounts.add(account);
    }
  }
 
  public void handle(PaidOffAccount event){
    Account account = _repository.get(event.accountId);
  
    if (paidOffAccounts.contains(account))
      return;
  
    if (closedAccounts.contains(account)){
      sendNotice(account);
      closedAccounts.remove(account);
    } else {
      paidOffAccounts.add(account);
    }
  }
 
  private void sendNotice(Account account){
    _messageBus.publish(new NotifyOwner(account.ownerId));
  }
}

So, for many of the examples I've seen, a user creates Commands that are handed to a MessageBus that dispatches it to a subscribed CommandHandler. The CommandHandler loads the relevant Aggregate and calls methods on it. The resulting events are gathered, persisted (if doing Event Sourcing), and passed to the MessageBus. The subscribers to that event will often update some read model (effectively turning domain events into updates on report tables) but they may be Sagas that track events and create related commands when necessary.

None of that is the essence of DDD or the essence of CQRS, but it's so common to the discussions and examples that this little glossary helps me to keep things straight.

Typefull Dynamic API: a typesafe C# facade/adapter/monad with phantom types

2012-01-17T17:51:00.000-08:00

One of the things I came up with at home and actually got to implement at work is so useful, and novel to the C# crowd, that I thought I'd share. I call it a Typefull Dynamic API and it looks like an object that changes its public api at design time based on what would be the state of another object at runtime. Impossible? Nope. I'll even show you how you could have came up with it yourself.

The scenario

Imagine the following fictitious method:

public Account Example()
{
    var account = new Account();
    account.State = UsaState.California;
    account.Open();
    PeopleManager.SetAccountPeople(account, 0);
    MemberLevelServiceHelper.SetAccountHolderLevel(account, MemberLevel.Gold);
    new DebtCalculator().CalculateDebt(account);
    account.Complete();
    Reports.GetCompletedAccountReport().AddAccount(account);
    AccountUtil.Close(account);
    NoteAddingSingleton.Instance.AddNote(account, "I'm an example!");
    return account;
}

It looks like it creates an account, does some setup, and returns it. It's calling a bunch of things from all over the place. I know from experience that I'd have a hard time remembering where everything is and what order to call it in. Some things are on the account, some are singletons, some are helpers and utils - exactly the kind of situation that anyone who's joined a long term project with many other developers is familiar with. If only there was a unified interface for all these subsystems - oh wait - isn't that the definition of the classic Facade pattern?

The patterns

class AccountLifecycleFacade
{
    public Account RealAccount { get; set; }

    public AccountLifecycleFacade() 
    {
        RealAccount = new Account();
    }

    public void SetState(UsaState state)
    {
        RealAccount.State = state;
    }

    public void Open()
    {
        RealAccount.Open();
    }

    public void SetAccountPeople(int count)
    {
        PeopleManager.SetAccountPeople(RealAccount, count);
    }

    public void MakeGoldLevel()
    {
        MemberLevelServiceHelper.SetAccountHolderLevel(RealAccount, MemberLevel.Gold);
    }

    /* ... etc ... */
}

Having this facade lets us work through the lifecycle of an account without worrying about where that functionality is actually implemented; no more trying to remember which helper, manager, singleton, service, utility, or business class to use since we only need to look at one place. With one class for the hi-level functionality, we have a clear api and intellisense will show us what we can do with an account.

public Account FacadeExample()
{
    var account = new AccountLifecycleFacade();
    account.SetState(UsaState.California);
    account.Open();
    account.SetAccountPeople(0);
    account.MakeGoldLevel();
    account.CalculateDebt();
    account.Complete();
    account.AddToCompletedAccountReport();
    account.Close();
    account.AddNote("I'm an example!");
    return account.RealAccount;
}

And since it works with a single account at a time we can make it a wrapper. If we make the wrapper return itself at the end of each method then we'll be able to call it using a fluent interface.

class AccountLifecycleAdapter
{
    public Account RealAccount { get; set; }

    public AccountLifecycleAdapter(Account account) 
    {
        RealAccount = account;
    }

    public AccountLifecycleAdapter SetState(UsaState state)
    {
        RealAccount.State = state;
        return this;
    }

    public AccountLifecycleAdapter Open()
    {
        RealAccount.Open();
        return this;
    }
    /* ... etc ... */
}

And now our example method is a little simpler.

public Account Example()
{
    var account = new AccountLifecycleAdapter(new Account())
        .SetState(UsaState.California)
        .Open()
        .SetAccountPeople(0)
        .MakeGoldLevel()
        .CalculateDebt()
        .Complete()
        .AddToCompletedAccountReport()
        .Close()
        .AddNote("I'm an example!");

    return account.RealAccount;
}

That's much easier for me to read, understand, and test. I'm sure this facade/adapter has been done a hundred times before. I see one potential problem though: it looks like some of the methods are only valid at certain times. I'd wager that you can't complete a non-open account and that you really shouldn't add an account to the Closed Account Report until it's closed. We could rely on runtime assertions to verify the preconditions and post conditions of our new Account api, which is a fine idea, but wouldn't it be nice if we could catch this at compile time?

The magic

If the preconditions and postconditions of these methods were expressed in the type system then not only would the compiler stop us from running invalid code, but intellisence would only show the methods that are valid for the account we have. In order for that to work we need to change the type of our AccountLifecycleAdapter to expose the state of the account. For this example, certain things may only be valid when the account is new, opened, completed, or closed and certain things may only be valid for new, bronze, silver, or gold members. Not only do these methods have preconditions based on the status and member level of the account, but they also have postconditions that change the state of the account.

Some preconditions and post conditions of the domain methods.
Method	Precondition	Postcondition
Open()	Status = New	Status = Open
Complete()	Status = Open	Status = Complete
Close()	Status = Open or Complete	Status = Close
AddToCompletedAccountReport()	Status = Complete	Status is unchanged

Although we can change the state of an object, we can't change its type. Luckily we don't need to since we are returning an AccountLifecycleAdapter with each method: we can return a different type that represents the state of the account and only supports the methods that are valid for that account state.

One possible way is to have a new class for each possible state.

class AccountLifecycleAdapter_NewStatus_NoLevel
{
    public Account RealAccount { get; set; }
    public AccountLifecycleAdapter_NewStatus_NoLevel(Account account) 
    {
        RealAccount = account;
    }

    public AccountLifecycleAdapter_NewStatus_NoLevel SetState(UsaState state)
    {
        RealAccount.State = state; 
        return this;
    }

    public AccountLifecycleAdapter_OpenStatus_NoLevel Open()
    {
        RealAccount.Open();
        return new AccountLifecycleAdapter_OpenStatus_NoLevel(RealAccount);
    }

    /* ... etc ... */
}

This would make sure that the wrapper expresses the state of the account and that only valid methods are called for that account. But it could become a cartesian explosion; this example as 4 statuses and 4 member levels for a total of 16 classes you need to make. Since some things are applicable for several states (like CalculateDebt and Close from our earlier table), they'd need to be implemented in several different wrapper classes. Messy. Fortunately for C# users, the language offers a convenient way out by way of generics and extension methods. Instead of having the class name express the state, we can use a generic type parameter for each run time variable we wish to track; status and member level in this case. A method that creates a copy with the type parameters we want would let us chain the wrapped object along while changing the type parameters.

class AccountLifecycleAdapter<Status, Level>
{
    public Account RealAccount { get; set; }
    public AccountLifecycleAdapter(Account account)
    {
        RealAccount = account;
    }
   
  public AccountLifecycleAdapter<NewStatus, NewLevel> SetTypes<NewStatus, NewLevel>()
  {
    return new AccountLifecycleAdapter<NewStatus, NewLevel>(RealAccount);
  }
}

And a non-generic version will make sure we create the adapter with the correct default type parameters.

public class AccountLifecycleAdapter
{
  public static AccountLifecycleAdapter<New, NoLevel> New(Account account)
  {
    return new AccountLifecycleAdapter<New, NoLevel>(account);
  }
}

The methods that used to belong to the wrapper can now be moved into extension methods.

 public static class AccountLifecycleAdapterExtensions 
 {
  public static AccountLifecycleAdapter<New,NoLevel> SetState(this AccountLifecycleAdapter<New,NoLevel> adapter, UsaState state)
     {
         adapter.RealAccount.State = state;
         return adapter.SetTypes<New,NoLevel>();
     }
 
     public static AccountLifecycleAdapter<Open,L> Open<L>(this AccountLifecycleAdapter<New,L> adapter)
         where L : AccountLevel
     {
         adapter.RealAccount.Open();
         return adapter.SetTypes<Open,L>();
     }
  
  public static AccountLifecycleAdapter<Open,L> SetAccountPeople<L>(this AccountLifecycleAdapter<Open,L> adapter, int count)
   where L : AccountLevel
     {
         PeopleManager.SetAccountPeople(adapter.RealAccount, count);
         return adapter;
     }

    /* ... etc ... */

If we look at our extension methods then we see something I think is very interesting. With this kind of typefull api, the input parameter type represents the precondition and the return type represents the post condition.

public static AccountLifecycleAdapter<Open,L> Open<L>(this AccountLifecycleAdapter<New,L> adapter) 
    where L : AccountLevel

Method	Precondition	Postcondition
Open	Status = New	Status = Open

Since the valid status is expressed as a precondition and the what the method changes is expressed as the return type, the compiler and intelisense can make sure you only chain methods that make sense. If a method returns an AccountLifecycleAdapter<Open, Silver> then you can't call an extension method that expects a Closed account. Intellesence won't suggest invalid methods and the compiler won't allow them. As an added bonus, changing the preconditions or post conditions in a way that breaks code will prevent a compile instead of lying dormant until discovered, investegated, and fixed during manual or automated testing.

All we need now are the types that represent the runtime state.

The Phantom Types

These types are a little odd in that they are only used for compile time info and we never create instances of them. The Haskell community would call them Phantom Types so we should too.

namespace PhantomTypes
{
    public abstract class PhantomType {}

    public abstract class AccountStatus : PhantomType {}
    public abstract class New : AccountStatus {}
    public abstract class Open : AccountStatus {}
    public abstract class Completed : AccountStatus {}
    public abstract class Closed : AccountStatus {}

    public abstract class AccountLevel : PhantomType {}
    public abstract class NoLevel : AccountLevel {}
    public abstract class Bronze : AccountLevel {}
    public abstract class Silver : AccountLevel {}
    public abstract class Gold : AccountLevel {}
}

I like to make it double obvious that these are different than normal types with a separate PhantomType namespace and PhantomType base class.

Since the type parameters are part of the method signature, you can have different overloaded methods for different states. Here we can see that an overdraft will close the account unless it's a gold level account; they just get a warning.

    public AccountLifecycleAdapter<S,GoldLevel> Overdraft<L>(this AccountLifecycleAdapter<S,GoldLevel> adapter)
        where S : AccountStatus
    {
        NotificationService.GetInstance().NotifyOfOverdraft(adapter.Account);
        return adapter.SetTypes<S,GoldLevel>()
    }

    public AccountLifecycleAdapter<Closed,L> Overdraft<S,L>(this AccountLifecycleAdapter<S,L> adapter)
        where S : AccountStatus
        where L : AccountLevel
    {
        AccountUtil.CloseDueToOverdraft(adapter);
        return adapter.SetTypes<Closed,L>()
    }

Interfaces can be used if an extension method will work with multiple different phantom types.

  public abstract class AccountStatus : PhantomType {}
  public interface NotNew { }
  public abstract class New : AccountStatus {}
  public abstract class Open : AccountStatus, NotNew {}
  public abstract class Complete : AccountStatus, NotNew {}
  public abstract class Closed : AccountStatus, NotNew {}

And the method that uses it would add that as a type parameter constraint.

     public static AccountLifecycleAdapter<S,L> AddNote<S,L>(this AccountLifecycleAdapter<S,L> adapter, string note)
         where S : AccountStatus, NotNew
   where L : AccountLevel
  {
   NoteAddingSingleton.Instance.AddNote(adapter.RealAccount, note);
         return adapter;
  }

Where to go from here

A lot more functionality and safety can be added. One idea is to add a check to the adapter's constructor or SetTypes method that asserts the phantom types match the actual run time state. This would let you know if your expectations of what's going on are correct or not.

public void CheckTypes<NewStatus, NewLevel>()
{
    if (typeof(GoldLevel).IsAssignableFrom(typeof(NewLevel)) && RealAccount.MemberLevel != MemberLevel.Gold)
      throw new InvalidOperationException("expected account member level Gold; got " + RealAccount.MemberLevel);
}

Another thing the adapter could do is collect all the ancillary objects that get created along the way. That way, once you're done with it you not only have your account, or whatever you were making, but any other related objects and you won't need to query for them.

One idea I haven't tried (yet...) is generating documentation about the system based on the adapter's extension methods. If you think about it, each of these methods is a transition from preconditions to postconditions. Each precondition and postcondition would be a state. You could use reflection, or old fashioned string manipulation, to capture all of the states and transitions within an adapter and create a state transition diagram. In a complex system this could be very useful for explaining the system to new hires, managers, users, other developers, or testers. Speaking of testing, knowing all of the different states transitions would also help ensure you are adequately testing all code paths.

I'm not entirely sure what to call this construct or "pattern". It's sort of the opposite of the State pattern; instead of an object changing behavior at run time, it's exposing a different api at design time. It's sort of like a Builder since you're building an object through a path that's more complex than a simple constructor. It can be a Facade and call other sub systems, but it doesn't have to be. It's also an Adapter since it exposes functionality related to the wrapped object. In my mind, the important thing is that it this is an adapter that only exposes methods that are valid for the run time state of the wrapped object. For now I'm calling this a Typefull Dynamic API but there may be a better name.

The Summary

Using the facade pattern can greatly aid in readability, understandability, and testability of a complex system with many subsystems - that's been known by many people for many years now. Using an object that returns itself in each method makes fluent interfaces possible - that's been known for a few years too. And using the signature of the method to express the preconditions and postconditions and making sure things are only called on object with the correct state has been around for decades, although I think the object oriented crowd has missed out on a lot of this since you can't change the type of an object when its state is changed. Extension methods give C# developers a chance to combine these in a useful way to get something new: a Typefull Dynamic API that changes its public api at design time based on what would be the state of another object at runtime.

The simplest typesafe EventBus

2012-01-10T17:48:00.000-08:00

I'm a big fan of typesafety so while exploring messaging and events, I've also tried my own typesafe EventBus:

public static class EventBus
{
  private static Dictionary<Type, List<Action<object>>> handlers 
      = new Dictionary<Type, List<Action<object>>>();
  
  public static void Subscribe<T>(Action<T> handler){
    if (!handlers.ContainsKey(typeof(T)))
      handlers.Add(typeof(T), new List<Action<object>>());
   
    handlers[typeof(T)].Add(e => handler((T)e));
  }
  
  public static void Publish<T>(T e){
    var eventType = typeof(T);
   
    foreach (Type handlerType in handlers.Keys)
      TryPublishForType(handlerType, eventType, e);
  }
  
  private static void TryPublishForType(Type handlerType, Type eventType, object e){
    if (handlerType.IsAssignableFrom(eventType))
      handlers[handlerType].ForEach(handler => handler(e));
  }
}

It's very similar to the simplest event bus. I'm sure there are other ways of tracking what subscribers can handle each event but the Dictionary<Type, List<Action<object>>> works well enough. If you're not used to Haskell or C# type trickery then it may seem too complex either way but I think much of that is caused by how verbose C# tends to be.

One neat thing about typesafe event busses is that, if designed for it like this one is, they can respect the inheritance tree. That means if an Action<object> is subscribed, then it will get everything that get's published since all events are assignable to object. This also means that it is backwards compatible with the simplest EventBus. A few subscribers may need to explicitly state the event type they are interested in but if they use object as the type parameter when subscribing, then the behavior should be the same.

The simplest EventBus

2012-01-04T15:31:00.000-08:00

I've been playing a lot with event buses, domain events, messaging, or whatever you want to call it. I've seen some open source event buses but they looked pretty complicated and often had a lot of extra baggage that clouded what I was interested in: exploring different ways to decouple collaborating classes. I had enough of that and set out to find the simplest thing that would get the job done and here's what I came up with:

public static class EventBus
{
  private static List<Action<object>> handlers = new List<Action<object>>();
  
  public static void Subscribe(Action<object> handler)
  {
    handlers.Add(handler);
  }
  
  public static void Publish(object e)
  {
    handlers.ForEach(handler => handler(e));
  }
}

That's it. No unsubscribing, multithreading, xml configuration, flexible dispatching strategies, subscription tokens, base classes, interfaces, or attributes. You don't have to use any specific interfaces to subscribe or publish. You don't even have to instantiate it - it's always ready. Anything can subscribe, anything can publish, from anywhere in your project. Anything can be published and every subscriber will get it. Want to publish an AccountClosed domain event? Go for it. Want to publish a naked string or int? Go ahead. How about publishing your entire Windows Form? I'm not sure why you would, but this won't stop you.

Just one line to wire-up a subscription (often called from Main):

public static void AddSubscriptions(ILogger logger, PopulationReport pop, MainApp app)
{
  EventBus.Subscribe(e => logger.Log(e.GetType().Name + ":" + e.ToString()));

  EventBus.Subscribe(app.HandleEvent);

  EventBus.Subscribe(e => {
    if (e is CreatureCreated)
      pop.CreatureCreated(((CreatureCreated)e).Creature);
    else if (e is CreatureDied)
      pop.CreatureDied(((CreatureCreated)e).Creature);
  });
}

And one line to publish (often called from domain objects):

public void Die()
{
  this.health = 0;
  EventBus.Publish(new CreatureDied(this));
}

It can be a bit on the slutty side since it's globally accessible and subscribers will get everything that's published, but that comes with benefits too. This is a good starting point and I haven't had any problems with it: the type checking is minimal for subscribers, I've never tried to subscribe a null, and I don't mind having my domain objects explicitly depend on it. You could add a ClearSubscribers method or a SetInstance method for unit testing, but I just use a single subscriber that dumps all events into a list when a unit test needs to ensure that specific events were created. In the last few at home projects I've worked on this has been the only static class I've used since this is one of the very few times that I'm in favor of a static class with behavior and state.

I find it much easier to learn about something when it's striped of all the unnecessary fluff. Event busses, domain events, messaging, whatever you want to call it is, in my mind at least, really just easy, ubiquitous, and loosely coupled communication.

From collaborator hell to dependency-free bliss

2011-12-28T15:08:00.000-08:00

Let's say you're a developer on a C# app and just got a batch of new requirements. Let's also say that it has a fairly simple requirement: when a user closes his or her account, the account status should be set to closed. You, as a good Test Driven Developer, write your unit test, watch it fail, then add the following code to the Account class and watch your test pass:

public void Close() {
  this.Status = AccountStatus.Closed;
}

Easy-peasy.

Many weeks later you come across a requirement that says when a user closes his or her account, the account owner's IsSpecial flag should be set. To make your latest unit test pass, you do the simplest thing that could possibly work.

public void Close() {
  this.Status = Status.Closed;
  this.Owner.IsSpecial = true;
}

Your test went from Red to Green and now it's time to Refactor. Having your Account mutate some value on another object breaks encapsulation so you Control+R & E to Extract Method then Control+R & M to Move your method to the Owner class and give it a clear name.

public void Close() {
  this.Status = Status.Closed;
  this.Owner.ClosedAccount(this);
}

That's a little better. In stead of just setting some property you're now telling the other object that something happened. It's free to handle that how it wants and the Account needn't know about it - a textbook case of encapsulation and The Hollywood Principle.

You've worked in this domain long enough to know that all kinds of things are going to happen when an account is closed. Maybe the other things should be moved to a different method? Not entirely YAGNI, but modifying the account and telling others about it are two different things so you could make the argument that they should be two separate methods.

public void Close() {
  this.Status = Status.Closed;
  this.OnClosed();
}

private void OnClosed(){
  this.Owner.ClosedAccount(this);
}

It's a judgment call but this does clearly separate things. There's one method where the account modifies itself and another where all the other objects get to react to the account being updated. You know that if you have requirements that start with when an account is closed, then the code that deals with the account should go in the Close method and code that deals with other classes goes in the OnClosed method. But wait a second - doesn't this sound familiar? There's even something built into the C# language for just this scenario: events and delegates.

public delegate void ClosedEventHandler(object sender, AccountClosedEventArgs e);

public class Account {
  public event ClosedEventHandler Closed;

  public void Close() {
    this.Status = Status.Closed;

    if (this.Closed != null)
      this.Closed(this, new AccountClosedEventArgs(this));
  }
}

Now the owner can register a callback with the account's Closed event and the account can just tell whoever's listening when it has closed. The Account class no longer needs to reference the Owner class and we can rejoice.

But something about this still doesn't quite seem right. Now instead of the Account telling the Owner, the Owner has to listen to the Account. You still have one class directly referencing and depending on another - you just switched the dependency direction. A day or two later you remember you once read something about Messaging and Domain Events so you look it up and get that started.

public void Close() {
  this.Status = Status.Closed;
  EventBus.Publish(new AccountClosed(this));
}


/* ... elsewhere ... */
public class AccountClosed{
  public Account Account { get; set; }

  public AccountClosed(Account account){
    this.account = account;
  }
}


/* ... elsewhere ... */
class AccountEventsHandler {

  private IRepository repository;

  public AccountEventsHandler(IRepository repository){
    this.repository = repository;
  }

  public void Handle(AccountClosed e){
    this.repository.GetOwner(e.Account).IsSpecial = true;
  }
}


/* ... elsewhere ... */
public void WireEverythingTogether(IRepository repository){
  var accountHandler = new AccountEventsHandler(repository);
  EventBus.Subscribe<AccountClosed>(accountHandler.Handle);
}

Much nicer. Not only is the dependency completely removed from the Account and Owner classes, but each class no longer exposes methods that are just used for reacting to each other. The Account only modifies itself and creates events and the Owner only modifies itself and creates events. Now you have the Account depend on the EventBus and somewhere else you subscribe other classes to the appropriate events. You have a simple AccountEventsHandler that deals with coordinating other objects when the account changes so the domain objects themselves don't need to. It can be little bit more work, but it does reduce coupling and allow much cleaner domain objects. But the Account is still referencing the EventBus directly. You could use a service locator:

public void Close() {
  this.Status = Status.Closed;
  Services.Get<IEventBus>().Publish(new AccountClosed(this));
}

But the service locator can cause problems - like if an IEventBus wasn't registered - and is considered an anti-pattern by some people. You could use constructor injection to pass in the dependency instead.

public Account(IEventBus bus){
  this.eventBus = bus;
}

public void Close() {
  this.Status = Status.Closed;
  this.eventBus.Publish(new AccountClosed(this));
}

That's clean and a good use of the Dependency Inversion Principle, but maybe overkill since the EventBus is so simple and ubiquitous. Maybe hard coding a such a simple dependency is ok. In my limited experience this is an acceptable time for bending the rules and relying on a statefull static class. You will probably never hear me say that again since I hate working with static classes and singletons that have state or complex behavior. On the other hand, constructor injection is a great first step to using a Dependency Injection Container to wire up the EventBus and other dependencies.

Maybe months from now you can switch to actual full-scale event sourcing and CQRS. With command handlers, the Domain Objects create events and store them locally. Then the command handler would fetch all the events from the domain objects and pass them to the event bus; your domain objects don't even need to know about the event bus anymore since the command handler deals with that.

This series of slightly different ways of dealing with different objects involved in the same action is something that I've had a lot of problems with. It's all the same basic result but the important difference is in how to deal with coordinating different objects when something happens. These different designs have very different benefits and costs. The earlier examples are easy for anyone to do, easy to see exactly what happens when debugging or looking at the code, and you know exactly where to make the change: right in the method itself. The downside is that it becomes collaborator hell and all your classes quickly become so bloated that most of the class's code is actually about other classes. The classes become so interdependent that you can't change one thing without having to change everything else. Having lots of dependencies like this can also make build times suffer too. The latter examples only rely on the Event Bus, Service Locator, or Inversion Of Control Container so they are as non-dependent as possible but I can't really tell what's going to happen when the program runs. If everything is wired together with configuration in xml files or sql tables then it can also become exceedingly tedious and error prone to change. This kind of configuration becomes especially difficult if the developer's environment, qa environments, and production environments can all be configured differently. Not everyone will be familiar with or even like the event-based designs either. The whole thing is made even more confusing if different sections of the project have different ways of doing things and people mostly just do whatever they copied and pasted from - not that I've ever done that of course....

Randomized metroidvania update: simple fix

2011-12-04T22:38:00.001-08:00

I decided to take a break from skeletal animation and focus more on the room generation for the Metroidvania game. While implementing architecture and art for underground caves, I think I found out how to fix the problem where transitioning into a new room would "bump" you to an unexpected place. I say that I "found out" instead of "figured out" because it was really just a lucky observation and a lot of trial and error.

Why did it take me so long to figure that out? Well, the problem seemed to only happen when transitioning from one room to another room, while on the floor (i.e. not jumping), where the new room's ceiling was lower on the world map than the room you were transitioning from. Confusing enough? Even then, it only happened some of the time. After a lot of logging, I noticed an odd pattern: the player's new y coordinate would be slightly higher than expected (by less than a single pixel). After all that, here's the fix:

private function checkBounds():void
{
    /* code to figure out the new room and new player.x and player.y values */

    if (toRoom.mapY > currentRoom.mapY)
        player.y -= 1; // gravity causes weird things sometimes....   
}

Although I'm glad to finally have this fixed, as far as I can tell at least, I'm still annoyed by it. What annoys me most is that I have no idea how I could have prevented this and no idea how to even figure out this fix. It was a lot of observation and trial and error. There were at least a dozen previous attempted fixes that didn't fix anything. I still don't fully understand why having a y coordinate of 144 is ok but one of 144.00115 causes you to fall to the room below and have a different x coordinate. I don't even know how to write a unit test for this: it involves Flixel physics, Flixel collision detection, and the constantly changing algorithms that I use to create rooms. Could TDD have prevented this? Is there a unit test that reliably shows what the bug was?

Skeletal animation with actual images

2011-11-22T08:15:00.001-08:00

It took quite a while because I was busy with other things and because I tried to do too much at once. Once I broke the problem down into smaller pieces, things quickly fell into place. I had to rewrite most of the underlying bones and joints but I eventually got the skeletal animation to work with actual graphics. Here's a half-sized Galamoth from C:SOTN.

I completely got rid of bones and just use FlxSprites now. Each FlxSkeletonJoint is responsible for how the parent and child are positioned relative to each other. Joints do this by attaching the "ball" point of one sprite to the "socket" point of another at a given angle. Each joint can still have it's own set of animations. The FlxSkeleton itself just holds the bones and joints and helps assemble and detatch them.

Next is basic inverse kinematics - just enough to support things like "look at that" or "put your right hand here". That should be good enough for what I need.

Skeletal animation with basic physics

2011-11-14T19:16:00.001-08:00

Skeletons are now FLxObjects and not FlxGroups. There's a few other minor changes but that's the big one. You can see the bounding box by toggling debug mode by pressing [~] then clicking the bounding box icon in the upper right.

Press [w] to jump, [a] or [d] to walk, hold [shift] to run, and [k] to kill yourself. There's not really anything to do here - just jump around and self-kill when bored.

Completed this time:

Make sure skeletons play well with Flixel physics (collisions, velocity, acceleration, etc.)
Detaching bones (exploding skeletons!)
More animations for HumanoidSkeleton

Next up:

Make sure regular sprites and animated sprites can be used as bones
Constraints for joints
Ragdoll physics

Skeletal animation with forward kinematics

2011-11-11T16:34:00.000-08:00

I'm off to a good start with my little detour into skeletal animation: I've got bones and joints that can be animated. The joints use keyframes to hold the target angle of the joint and interpolate between the current angle and the target angle so switching animations should smoothly transition from one to the other. I had a bit of difficulty since rotating a FlxSprite rotates about the center and I need to rotate around the joint. I also wasted nearly an hour on a really stupid bug where animating a joint would sometimes make it freak out (hint: -45 as a Number and -45 as a uint are two very different values). Once I'm done, I plan on submitting a pull request to the original Flixel project so maybe the next version of Flixel will support skeletal animations....

Done so far:

FlxSkeletonBone - a FlxSprite with a start and end point
FlxSkeletonJoint - a class that connects bones at an angle
FlxSkeleton - a FlxGroup that wires everything together
HumanoidSkeleton - a pre-made human skeleton with some generic animations
Keyframe based animations per joint
Simple forward kinematics

To do:

Make sure regular sprites and animated sprites can be used as bones
Make sure skeletons play well with Flixel physics (collisions, velocity, acceleration, etc.)
Constraints for joints
Ragdoll physics
Detaching bones (exploding skeletons!)
Add inverse kinematics
More animations and helpers for HumanoidSkeleton
Walking velocity determined by feet positions?

Randomized metroidvania 09: slightly better architecture

2011-11-07T14:38:00.000-08:00

It took a few days longer than I'd like but I was able to implement some new stuff:
    Slopes and stairs based off of https://github.com/krix/SlopesTest/blob/master/src/FlxTilemapExt.as
  Different background colors, patterns, and decorations (just columns for now)
    Different art and architecture preferences for each region

Each region gets a few architecture and art preferences. The architecture preferences are used to determine the room generation: what tiles are empty, solid, or stairs. The art preferences are used to determine the graphics: what do the background, stairs, walls, and floors look like. There's still not much content but I have a simple system set up and I can add more and better art or architecture styles later. Alpha content will suffice for now.

There's still a bug where moving into another room sometimes bumps you to a different space. I can't pinpoint where or why though. It seems to only bump you towards the bottom of the map and never the top. It also seems to bump to the left and never the right. So it bumps up the Y axis and down the X axis.... weird.

I think it's time to focus on player graphics for a while. Since I'm better at programming than art, I think I'll try my hand at skeletal animation. Flixel doesn't have anything like this as far as I can tell but forward and inverse kinematics should be fun and make a lot of the art stuff easier too. I estimate about a week until I have something useful.

Randomized metroidvania 08: initial architecture

2011-11-04T19:33:00.000-07:00

I've got some initial architecture. It should now be possible to move from any room to any room. It certainly ain't pretty and is sometimes frustrating to get the jumps but it does allow you to get from one room to the next. I also added restricted regions to the world generation so the resulting map won't be as dense.

[it seems that transitioning from one room to the other sometimes "bumps" the player to a different spot... worked fine on my machine. I'll look a little closer into that code.]

Part of automating the process of creating room internals was changing the screen size to 32x21 tiles. Next up is adding sloped tiles for stairs, more variety, and more randomness to the architecture.

Randomized metroidvania 07: a brief study of C:SOTN and vertical movement

2011-11-02T19:56:00.000-07:00

Next up is adding stairs, lifts, and all the architecture that should go in a room. It's already possible to move to rooms to the left and right, but moving up the map isn't possible yet. I decided to turn to maps of Castevania: Symphony Of The Night to see how they did it.

First of all, Alucard seems to be two tiles wide and three tall. When he jumps his feet are 4 tiles higher than they were when he started. This means that the shortest ceiling is 3 tiles from the floor and he can jump onto a tile that has a top that's 4 tiles off the floor.

Sometimes a flight of stairs or a hole in the floor is good enough to go up. The second image has three tiles from the top of the stairs to the bottom of the next floor - just short enough to jump up.

Sometimes you have to make a series of jumps between sides and center blocks.

Jumping back and forth between side platforms is the most common. These pictures show that sometimes it's more obvious than other times.

Here's a short series of jump-through blocks.

This could be either a series of jump-through blocks or jumping from side to side depending on how you look at it. This pattern shows up in a few places.

There are also a few places with moving platforms to bring you up or down.

And this is my favorite example: a weird mix of side to side, stairs, and just jumping up through a hole in the floor. I don't remember if it's here or another place but I think you can't get to some of the non-essential side platforms until you have double-jump. The background graphics and variety make it much more interesting.

A simple algorithm for this might be: evenly place floors, add a flight of stairs going up each third floor, remove the floor from the top of the stairs to the opposite wall, remove the floor form the base of the stairs to the nearest wall, and add a gap in each remaining floor. The background shadows, floors, stairs, and banisters at the top of the staircases are good examples of the attention to details found in C:SOTN.

So it seems that sometimes you just walk up some stairs or do a single jump, at other times you have to jump from side to side, or sometimes from sides to center blocks, or even have to jump through one-way blocks. The best places (in my opinion) are a crazy mix of each. This is probably much easier to automate if your screen can be split into an even number of floors like the last image; that way you could place the floors and then pick random ways to move between them. It's also good to point out that each region has it's preferred method for going up. Don't forget to carefully plan the architecture to match the height and jump hight of the main character.

This may have been pretty obvious to most of you, but I learned a lot: you can use the same action (jump to the upper left then the upper right then the upper left....) but provide slight differences in art and layout and it will still provide interesting architecture and opportunities for fun. I've also got some working code to create rooms with layouts like the last image. And lastly; after 15 years, C:SOTN is still a beautiful and intricate game.

Randomized metroidvania 06: player in a room

2011-11-01T19:19:00.000-07:00

I slept through my alarm this morning and woke up 4 hours after I should have been at work so I had a lot of time for this project today.

Time for the first steps to actual gameplay: a rectangle that can walk and jump around empty rooms. Press [m] to view the map.

Nothing exciting yet - just rooms with connections to the neighboring room. There's not even a way to go up stairs or anything so you eventually end up at a dead end. It was tricky getting the player to walk out one door and appear in the correct one in the correct room; it would have been easier to just create one huge map with the entire level but that would take a lot of memory and the camera would look into rooms you haven't been into yet. Next I'll add background graphics along with stairs and floors within each room; later the room sizes and shapes can be determined by the region. I'll also make sure the map only shows rooms you've been into and a few more tweaks. The really fun stuff will begin once I can generate some decent architecture. I should think of an overall theme I'd like to work with too.

Randomized metroidvania 05: map specials

2011-10-31T23:52:00.000-07:00

I was going to create the player and rooms to move around in but I decided to add a little more to the map. The very crowded map now shows bonus items in dead ends and secret rooms. You can also mouseover a room to see details about it's region, name, and contents.

There's a limited amount of keys and locks so if you add enough regions then you'll see "key #33" or something like that.

Here are some things I added:
for each unlocked dead end, there's a chance of adding a random lock and bonus
when placing a room, there's a chance of adding a secret room
when placing a room, there's a chance of a name and or some item

I'm not sure what theme or items I want in the final game, the ones here are just examples. Once I get the mechanics figured out (like how to create an interesting map) then I can figure out what theme I want to have.

I think I've crammed all I can into the map for now; time to start on actual gameplay.

Randomized metroidvania bugs

2011-10-30T12:55:00.000-07:00

My last post had a bug where new regions may not connect to a neighboring room. I thought about fixing it before posting but decided to post it anyway. Now I hate buggy software as much as anyone, and this bug makes the map unsolveable since there can be rooms you can't get to, so why did I post it anyway?

This is a work in progress and sometimes - most of the time - those are messy. Sometimes it's good to see how things are made, bugs and all.
I already fixed it when I changed that part of the code for my next iteration.

So what caused the bug in the first place? I changed the code that connects a room when it is placed. I made it keep placing connections until the new room is connected to another room in the same region unless it was the first room in that region. Otherwise a room could be placed and it would connect to a neighboring room from a different region and not connect to a room in it's own region. If that was the room that had the key and it was locked with that corresponding lock, then there was no way to get the key. In fixing that bug I introduced a new one.

Randomized metroidvania 04: map keys and locks

2011-10-30T12:30:00.000-07:00

It took a few hours and I had to rewrite the code for doors, but I've got keys and locks working. A major part of any metroidvania is exploring new areas and finding some kind of impassable barrier - a wide pit, a wall of metal blocks, a force field, etc. It's only later when you find some new ability or item - double jump, rocket launcher, field disabler, etc - that you can go past the barrier to a new region. You can abstract this idea of obstacles and items as "locks" and matching "keys". In one game the "red locks" and "red key" might represent actual locked doors and a key, in another game they might be security cameras and a disguise, and in another game they might be tall walls and the ability to climb walls.

You can see the locks and keys in my latest update. The icons are ugly and hard to distinguish, but it's just for example and will be redone many times before the project is over. Consider this the "alpha version" artwork.

[I just noticed that sometimes the first room in a region doesn't connect to the other rooms. A bug I just fixed when I redid that code for my latest work.]

when visiting a region for locks and keys:
place an unused key
put the matching lock on one door to each unvisited adjacent region
any unlocked doors to adjacent regions are added to a "to do" list
visit each unvisited adjacent region

after visiting all regions for locks and keys:
for each unlocked door on the "to do" list, put a random used lock

This ensures that each region has a key that you need to proceed to the neighboring regions. Although; since each region can connect with its neighboring regions multiple times, it's theoretically possible that getting the first key would be enough to explore all regions.

Randomized metroidvania 03: map regions

2011-10-29T15:23:00.001-07:00

Different regions! It was easier than I thought it would be - of course it has been in the back of my head for a while so I didn't jump in with my first thought.

to start a new region:
create a list of all frontiers for all rooms
randomly pick one to start the new region
clear all other frontiers
place a room as normal

The current region determines the room color and a randomly chosen maximum height and width and can easily be used to control more things like the artwork, items, bad guys, secrets, and other things. Like placing doors, this algorithm is guaranteed to connect with existing regions and could even connect multiple other regions.

Randomized metroidvania 02: map connections

2011-10-29T10:44:00.000-07:00

The rooms are now connected! I used a very simple method that's guaranteed to connect and will even create loops to join different "branches" that happen to be near by.

to connect a room:
after placing a room
get a list of all adjacent cells that are in a room
randomly pick some cells to create doors

This can create multiple opening between two rooms. That's not a problem yet but it could be tweaked later on. This should be enough to create the gameplay portion but I'd like to work on defining different regions at the world-gen level before I move on to creating a player to run around.

Randomized metroidvania 01: map rooms

2011-10-28T22:56:00.000-07:00

So I've decided to make a randomized metroidvania game; sort of a cross between a roguelike and one of the greatest games ever, Castlevania: Symphony Of The Night. Since I want this to be a flash game, I'll use Eclipse and Flixel.

I spent a few hours getting Eclipse to work with Actionscript and playing with Flixel a bit. For my game I decided to start with generating a random world map.

Here's the basic algorithm, which took less time than setting up Eclipse and Actionscript:

to start:
add a 1x1 "frontier" space
add a room

to add a room:
randomly pick a frontier space
start a room there
randomly grow it for a while
remove frontiers under it
add its empty neighboring cells to the list of frontiers

roguelike tutorial retrospective

2011-10-28T13:00:00.000-07:00

Time for a retrospective! I think retrospectives are probably the most important thing a developer could do since reflecting on what you've done is the difference between someone with 10 years of experience and someone with 1 year of experience repeated 10 times. There are as many different styles of retrospectives as there are teams who do them but I've found that these few questions are usually good enough for me.

What does this retrospective cover? For this roguelike tutorial I tried a few new and different things; the most obvious one being that this was a series of blog posts. This is also the first time I had something of a magic system. There were also a few tweaks to how I normally code things. The roguelike itself is not meant to be a complete and fun game - it's just a basic example of a few different things that may help some roguelike developers - so I'm not going to review the game as a game.

What worked well? As far as code goes, the Screen interface worked really well. Having goblins pickup and use items is neat, as is learning the identity of things by watching others use them. As far as a tutorial goes, I think it can be useful for some people. Even though like there are, at most, a handful of people who read each post, I did get more feedback than I expected, including a reference to behavior trees - something I didn't know about. I'm also pleased that my posts were a mix of code, references to other sources, and some of my own thoughts about why I'm doing what I'm doing. It's not as authoritative as saying "THIS IS THE ONE TRUE AND RIGHT WAY TO DO THIS", and some of it was probably a bad idea, but I've always found that the most instructive guides show the uncertainties and mistakes we run into and how to deal with them.

What needs to work better? One thing I've learned about building something via blog posts is that refactoring is very difficult to show; it's easy to show new code to add, especially if you have small classes and methods, but I don't know of any easy way to show removing, rewriting, and refactoring. This means that the final code, although mostly small pieces, could use a lot of cleanup work and this isn't representative of my best code and may even be a bad example. Oops. Using no globals was a laudable goal but lead to some things I'm not to happy about, like the path finder using a collection of points rather than a fixed size 2D array since I didn't have an easy way to tell the path finder what the map size is. There are a few minor annoyances with the code, like the creature class becoming a behemoth, but most of that is from adding features without refactoring. The spell-related code is quite ugly and clunky too - mostly because I'm not familiar with writing magic systems and couldn't refractor so it was just charging ahead with little idea what I was doing.

What should be done differently next time? I still think a series of blog posts can make a good tutorial but it needs something that makes it easier to show refactoring - perhaps putting everything on github and discussing the changes each time. That would be a slight improvement but still not quite good enough. I tried to be very structured to make sure I followed through and didn't lose interest halfway through but it would have been better to break it into more than 20 parts. I've used Ninject to make it easier to wire things together and something like that would work well for this kind of project; I thought about it but didn't want to add another post about how to use a dependency injection framework.

In summary

Use something to counter the limits to show refactoring on a series of blog posts.
Don't limit yourself to a fixed number of posts.
The Screen interface was the best thing I did: keep doing that.
The AsciiPanel was useful but it needs work to avoid flickering and to support animations.
Each post should have code, narration, references, and details about the author's thought process.
I liked getting comments from readers even more than I thought I would.

Any feedback from you, readers? What did you like? What did you not like? What could be done differently?

roguelike tutorial 20: item appearance and identification

2011-10-25T13:00:00.000-07:00

One of the things I enjoy the most about roguelikes is identifying items. Usually not by scroll of identify or funky unicorn tricks, but by boldly quaffing and reading — yeah, I tend to die a lot. Identification is something I haven't seen in other games and something that I think any good roguelike needs. The basic idea is that if we've identified an item, or given it a name of our own, then we see the name, otherwise we see it's appearance.

So let's start by adding an appearance to the Item class.

private String appearance;
public String appearance() { 
    if (appearance == null)
        return name;

    return appearance;
}

Then have it passed in to the constructor.

Since the appearance has to be passed in, our code is broken in all the places that create items - this is a good thing because now we can see what areas we need to change. If appearance is null then the name is used since most things look like what they are; e.g. a rock looks like a rock and a sword looks like a sword. Because of this we can pass a null appearance to all items except the potions. Before we get to the potions we need to set up some colors and text to use in our factory.

private Map<String, Color> potionColors;
    private List<String> potionAppearances;
 
    public StuffFactory(World world){
        this.world = world;
  
        setUpPotionAppearances();
    }
 
    private void setUpPotionAppearances(){
        potionColors = new HashMap<String, Color>();
        potionColors.put("red potion", AsciiPanel.brightRed);
        potionColors.put("yellow potion", AsciiPanel.brightYellow);
        potionColors.put("green potion", AsciiPanel.brightGreen);
        potionColors.put("cyan potion", AsciiPanel.brightCyan);
        potionColors.put("blue potion", AsciiPanel.brightBlue);
        potionColors.put("magenta potion", AsciiPanel.brightMagenta);
        potionColors.put("dark potion", AsciiPanel.brightBlack);
        potionColors.put("grey potion", AsciiPanel.white);
        potionColors.put("light potion", AsciiPanel.brightWhite);

        potionAppearances = new ArrayList<String>(potionColors.keySet());
        Collections.shuffle(potionAppearances);
    }

This creates some text ("red potion", "green potion") and some corresponding colors (red, green), and shuffles the text so each time you create a new factory they will be in a different order. Since we create a new factory once per game, each game will have different text and colors.

Now to set the potion color, just use the new data when creating potions.

String appearance = potionAppearances.get(0);
  Item item = new Item('!', potionColors.get(appearance), "health potion", appearance);

...and...

String appearance = potionAppearances.get(1);
  Item item = new Item('!', potionColors.get(appearance), "mana potion", appearance);

...etc.

Not the best way but it works well enough and is easy to show.

If you play the game the potions should be random colors now.

Our CreatureAi class needs to record what items have been identified and what the names of identified or renamed items are. We could have this tracked by the items themselves or some global variables, but this way creatures can identify and converse about item appearances too. By modeling it as close to reality as possible, i.e. where creature's have their own mind and names for items, interesting possibilities and emergent behavior are more likely.

private Map<String, String> itemNames;

    public String getName(Item item){
        String name = itemNames.get(item.name());
        return name == null ? item.appearance() : name;
    }
 
    public void setName(Item item, String name){
        itemNames.put(item.name(), name);
    }

And we need this to be available to the creatures.

public String nameOf(Item item){
    return ai.getName(item);
}
 
public void learnName(Item item){
    notify("The " + item.appearance() + " is a " + item.name() + "!");
    ai.setName(item, item.name());
}

Wherever we use an item's name we need to use nameOf instead. The easiest way I can think of doing this is to make the name method private and see where the code breaks. Those places need to use the creature's nameOf method instead. The only places we need the real name is in the PlayScreen where we check to see if the player has the Teddy Bear, or whatever the victory object is, and in the CreatureAi getName and setName methods. Once we make all the other changes we can make the name method public and everything should compile again.

Run it and you should see that potions are now listed by color instead of the real name. I got an error when starting but that was fixed by setting up the GoblinAi before the Goblin is given a weapon and armor.

Now we need to let the player identify things when used. In the StuffFactory, for each quaffEffect make the creature learn the name of the potion if any effect happens. Here's an example:

public Item newPotionOfHealth(int depth){
    String appearance = potionAppearances.get(0);
    final Item item = new Item('!', potionColors.get(appearance), "health potion", appearance);
    item.setQuaffEffect(new Effect(1){
        public void start(Creature creature){
           if (creature.hp() == creature.maxHp())
               return;
    
           creature.modifyHp(15);
           creature.doAction("look healthier");
           creature.learnName(item);
       }
    });
  
    world.addAtEmptyLocation(item, depth);
    return item;
}

The Creature's throwAttack should also let the thrower learn the name of anything that has a quaffEffect. Now when you play you can learn the identity of potions by quaffing or throwing them.

It's still possible to learn the name of an Effect that you shouldn't learn. If you kill a bat with a yellow potion you shouldn't be able to see the effect it had or identify what the potion is since the bat died from being hit by a bottle and there wasn't anything left for the effect to apply to. Let's create a version of the doAction method that handles this logic. This version of doAction will take a message and an item. Anyone who can see the creature should see the message and learn the identity of the item, unless the creature is dead, then nothing happens. We can reuse some of the code in the current doAction.

public void doAction(String message, Object ... params){
    for (Creature other : getCreaturesWhoSeeMe()){
        if (other == this){
            other.notify("You " + message + ".", params);
        } else {
            other.notify(String.format("The %s %s.", name, makeSecondPerson(message)), params);
        }
    }
}
 
public void doAction(Item item, String message, Object ... params){
    if (hp < 1)
        return;
  
    for (Creature other : getCreaturesWhoSeeMe()){
        if (other == this){
            other.notify("You " + message + ".", params);
        } else {
            other.notify(String.format("The %s %s.", name, makeSecondPerson(message)), params);
        }
        other.learnName(item);
    }
}
 
private List<Creature> getCreaturesWhoSeeMe(){
    List<Creature> others = new ArrayList<Creature>();
    int r = 9;
    for (int ox = -r; ox < r+1; ox++){
        for (int oy = -r; oy < r+1; oy++){
            if (ox*ox + oy*oy > r*r)
                continue;
    
            Creature other = world.creature(x+ox, y+oy, z);
    
            if (other == null)
                continue;
    
            others.add(other);
        }
    }
    return others;
}

A possibility:

The goblin quaffs a cyan potion.
The goblin looks stronger.
The cyan potion is a strength potion!

If the potions' quaffEffect use this new doAction then things will work a little better and we can remove the learnName from throwAttack since everyone who see's the creature will identify the potion based on the effect. This also means that if your creatures quaff potions everyone who watches can figure out what it is.

And that's one way of doing item identification. We had to make a lot of little changes all over the place, like using the creature's nameOf instead of the item's name method, but it wasn't difficult or error-prone. Each creature has it's own idea of what things are named so you could even let intelligent creatures tell each other the names. Maybe each goblin should quaff one unidentified potion during it's life and then discuss with others.

public void discussItemName(Item item, Creature other){
    creature.doAction(item, "say \"%ss are %ss\"", item.appearance(), item.name());
    other.learnName(item);
}

Or all goblins could share the same itemNames map — although that's kind of cheating.

You could also let the player give names to things. A RenameItemScreen that let's you rename a specific item or all items with a specific appearance. That way if the player deduces that red potions are healing potions then they can rename all red potions to healing potions or if they like their individual sword they can rename it Excalibur.

One last addition: add a "cause of death" string to the creature class and pass one in to modifyHp.

private String causeOfDeath;
 public String causeOfDeath() { return causeOfDeath; }
 
 public void modifyHp(int amount, String causeOfDeath) { 
     hp += amount;
     this.causeOfDeath = causeOfDeath;
  
     if (hp > maxHp) {
         hp = maxHp;
     } else if (hp < 1) {
         doAction("die");
         leaveCorpse();
         world.remove(this);
     }
 }

Then update the places that modify hp. Here's an example:

public void modifyFood(int amount) { 
    food += amount;
  
    if (food > maxFood) {
        maxFood = (maxFood + food) / 2;
        food = maxFood;
        notify("You can't belive your stomach can hold that much!");
        modifyHp(-1, "Killed by overeating.");
    } else if (food < 1 && isPlayer()) {
        modifyHp(-1000, "Starved to death.");
    }
 }

Then pass the player to the WinScreen and LoseScreen and you can tell the user details about how they died, what they were carrying, conduct, etc.download the code

roguelike tutorial 19: mana, spells, and magic books

2011-10-21T13:00:00.000-07:00

Time to add some magic to our game. This will take a lot of code and will take a long time to balance. To keep it simple, we'll just use mana and spellbooks. Scrolls are easy to add since they're basically potions that you read instead of quaff so I won't add scrolls - but I'm sure you can figure out how to do that by now or at least you will be able to after this tutorial.

We're going to have spells and each will have it's own effect. But when we add that effect to a creature, we want each creature to get it's own effect, otherwise weird things will happen because the spell will have an effect being applied to many creatures and the shared state (like duration) will be wonky. Instead, a spell will have an effect and when applying it to something we can create a copy and apply the copy. That way each time you cast a spell the effect will have it's own state. Add a copy constructor to the Effect class like this:

public Effect(Effect other){

    this.duration = other.duration; 

}

The first new class we'll need is a Spell class to tie together a spell name, cost, and effect.

package rltut;



public class Spell {



    private String name;

    public String name() { return name; }



    private int manaCost;

    public int manaCost() { return manaCost; }



    private Effect effect;

    public Effect effect() { return new Effect(effect); }



    public Spell(String name, int manaCost, Effect effect){

        this.name = name;

        this.manaCost = manaCost;

        this.effect = effect;

    }

}

See how we return a copy of the effect instead of the original?

Let's add the mana related stuff to the Creature class.

private int maxMana;

    public int maxMana() { return maxMana; }

    

    private int mana;

    public int mana() { return mana; }

    public void modifyMana(int amount) { mana = Math.max(0, Math.min(mana+amount, maxMana)); 

    

    private int regenManaCooldown;

    private int regenManaPer1000;

    public void modifyRegenManaPer1000(int amount) { regenManaPer1000 += amount; }



    private void regenerateMana(){

        regenManaCooldown -= regenManaPer1000;

        if (regenManaCooldown < 0){

            if (mana < maxMana) {

                modifyMana(1);

                modifyFood(-1);

            }

            regenManaCooldown += 1000;

        }

    }

Don't forget to initialize regenManaPer1000 in the constructor and to call regenerateMana during the update method. We also have something else we can gain during a level-up.

public void gainMaxMana() {

        maxMana += 5;

        mana += 5;

        doAction("look more magical");

    }



    public void gainRegenMana(){

        regenManaPer1000 += 5;

        doAction("look a little less tired");

    }

And add the new options to the LevelUpController.

new LevelUpOption("Increased mana"){

            public void invoke(Creature creature) { creature.gainMaxMana(); }

        },new LevelUpOption("Increased mana regeneration"){

            public void invoke(Creature creature) { creature.gainRegenMana(); }

        }

It would also be nice to add our new stats to the displayOutput method of the PlayScreen class.

String stats = String.format(" %3d/%3d hp  %d/%d mana  %8s", 

    player.hp(), player.maxHp(), player.mana(), player.maxMana(), hunger());

Adding spell books could be done many different ways. I think we should stick with the Item class and extend it with what we need.

private List<Spell> writtenSpells;

    public List<Spell> writtenSpells() { return writtenSpells; }



    public void addWrittenSpell(String name, int manaCost, Effect effect){

        writtenSpells.add(new Spell(name, manaCost, effect));

    }

Don't forget to initialize writtenSpells in the Item constructor. This should allow us to create scrolls, spell books, notes, or even engraved items. Very simple and flexible. If we create an effect that just displays a note to the user then we could even let the player add his own non-magical engravings to items.

Let's add some spell books. I'm going to create two simple ones but you should add more spells and more books. These are just examples of what can be done. The first is a healer type book:

public Item newWhiteMagesSpellbook(int depth) {

        Item item = new Item('+', AsciiPanel.brightWhite, "white mage's spellbook");

        item.addWrittenSpell("minor heal", 4, new Effect(1){

            public void start(Creature creature){

                if (creature.hp() == creature.maxHp())

                    return;

                

                creature.modifyHp(20);

                creature.doAction("look healthier");

            }

        });

        

        item.addWrittenSpell("major heal", 8, new Effect(1){

            public void start(Creature creature){

                if (creature.hp() == creature.maxHp())

                    return;

                

                creature.modifyHp(50);

                creature.doAction("look healthier");

            }

        });

        

        item.addWrittenSpell("slow heal", 12, new Effect(50){

            public void update(Creature creature){

                super.update(creature);

                creature.modifyHp(2);

            }

        });



        item.addWrittenSpell("inner strength", 16, new Effect(50){

            public void start(Creature creature){

                creature.modifyAttackValue(2);

                creature.modifyDefenseValue(2);

                creature.modifyVisionRadius(1);

                creature.modifyRegenHpPer1000(10);

                creature.modifyRegenManaPer1000(-10);

                creature.doAction("seem to glow with inner strength");

            }

            public void update(Creature creature){

                super.update(creature);

                if (Math.random() < 0.25)

                    creature.modifyHp(1);

            }

            public void end(Creature creature){

                creature.modifyAttackValue(-2);

                creature.modifyDefenseValue(-2);

                creature.modifyVisionRadius(-1);

                creature.modifyRegenHpPer1000(-10);

                creature.modifyRegenManaPer1000(10);

            }

        });

        

        world.addAtEmptyLocation(item, depth);

        return item;

    }

And the second has a hodgepodge of spells that do weird things, mostly to show what can be done within the effects:

public Item newBlueMagesSpellbook(int depth) {

        Item item = new Item('+', AsciiPanel.brightBlue, "blue mage's spellbook");



        item.addWrittenSpell("blood to mana", 1, new Effect(1){

            public void start(Creature creature){

                int amount = Math.min(creature.hp() - 1, creature.maxMana() - creature.mana());

                creature.modifyHp(-amount);

                creature.modifyMana(amount);

            }

        });

        

        item.addWrittenSpell("blink", 6, new Effect(1){

            public void start(Creature creature){

                creature.doAction("fade out");

                

                int mx = 0;

                int my = 0;

                

                do

                {

                    mx = (int)(Math.random() * 11) - 5;

                    my = (int)(Math.random() * 11) - 5;

                }

                while (!creature.canEnter(creature.x+mx, creature.y+my, creature.z)

                        && creature.canSee(creature.x+mx, creature.y+my, creature.z));

                

                creature.moveBy(mx, my, 0);

                

                creature.doAction("fade in");

            }

        });

        

        item.addWrittenSpell("summon bats", 11, new Effect(1){

            public void start(Creature creature){

                for (int ox = -1; ox < 2; ox++){

                    for (int oy = -1; oy < 2; oy++){

                        int nx = creature.x + ox;

                        int ny = creature.y + oy;

                        if (ox == 0 && oy == 0 

                                || creature.creature(nx, ny, creature.z) != null)

                            continue;

                        

                        Creature bat = newBat(0);

                        

                        if (!bat.canEnter(nx, ny, creature.z)){

                            world.remove(bat);

                            continue;

                        }

                        

                        bat.x = nx;

                        bat.y = ny;

                        bat.z = creature.z;

                        

                        creature.summon(bat);

                    }

                }

            }

        });

        

        item.addWrittenSpell("detect creatures", 16, new Effect(75){

            public void start(Creature creature){

                creature.doAction("look far off into the distance");

                creature.modifyDetectCreatures(1);

            }

            public void end(Creature creature){

                creature.modifyDetectCreatures(-1);

            }

        });

        world.addAtEmptyLocation(item, depth);

        return item;

    }

I had to add a couple methods to the creature class to support these.

public void summon(Creature other) {

        world.add(other);

    }

    

    private int detectCreatures;

    public void modifyDetectCreatures(int amount) { detectCreatures += amount; }

    

    public void castSpell(Spell spell, int x2, int y2) {

        Creature other = creature(x2, y2, z);

        

        if (spell.manaCost() > mana){

            doAction("point and mumble but nothing happens");

            return;

        } else if (other == null) {

            doAction("point and mumble at nothing");

            return;

        }

        

        other.addEffect(spell.effect());

        modifyMana(-spell.manaCost());

    }

And update one method:

public boolean canSee(int wx, int wy, int wz){

        return (detectCreatures > 0 && world.creature(wx, wy, wz) != null

                || ai.canSee(wx, wy, wz));

    }

You should also add a potion to restore mana.

Now we just need a ReadScreen to select an item to read, a ReadSpell screen to select a spell from the item, and a CastSpell screen to select a target for the spell. You should be able to figure those out but let's do them in the opposite order:

package rltut.screens;



import rltut.Creature;

import rltut.Spell;



public class CastSpellScreen extends TargetBasedScreen {

    private Spell spell;

    

    public CastSpellScreen(Creature player, String caption, int sx, int sy, Spell spell) {

        super(player, caption, sx, sy);

        this.spell = spell;

    }

    

    public void selectWorldCoordinate(int x, int y, int screenX, int screenY){

        player.castSpell(spell, x, y);

    }

}

The ReadSpellScreen is very similar to the InventoryBasedScreen.

package rltut.screens;



import java.awt.event.KeyEvent;

import java.util.ArrayList;



import rltut.Creature;

import rltut.Item;

import rltut.Spell;



import asciiPanel.AsciiPanel;



public class ReadSpellScreen implements Screen {



    protected Creature player;

    private String letters;

    private Item item;

    private int sx;

    private int sy;

    

    public ReadSpellScreen(Creature player, int sx, int sy, Item item){

        this.player = player;

        this.letters = "abcdefghijklmnopqrstuvwxyz";

        this.item = item;

        this.sx = sx;

        this.sy = sy;

    }

    

    public void displayOutput(AsciiPanel terminal) {

        ArrayList<String> lines = getList();

        

        int y = 23 - lines.size();

        int x = 4;



        if (lines.size() > 0)

            terminal.clear(' ', x, y, 20, lines.size());

        

        for (String line : lines){

            terminal.write(line, x, y++);

        }

        

        terminal.clear(' ', 0, 23, 80, 1);

        terminal.write("What would you like to read?", 2, 23);

        

        terminal.repaint();

    }

    

    private ArrayList<String> getList() {

        ArrayList<String> lines = new ArrayList<String>();

        

        for (int i = 0; i < item.writtenSpells().size(); i++){

            Spell spell = item.writtenSpells().get(i);

            

            String line = letters.charAt(i) + " - " + spell.name() + " (" + spell.manaCost() + " mana)";

            

            lines.add(line);

        }

        return lines;

    }



    public Screen respondToUserInput(KeyEvent key) {

        char c = key.getKeyChar();



        Item[] items = player.inventory().getItems();

        

        if (letters.indexOf(c) > -1 

                && items.length > letters.indexOf(c)

                && items[letters.indexOf(c)] != null) {

            return use(item.writtenSpells().get(letters.indexOf(c)));

        } else if (key.getKeyCode() == KeyEvent.VK_ESCAPE) {

            return null;

        } else {

            return this;

        }

    }



    protected Screen use(Spell spell){

        return new CastSpellScreen(player, "", sx, sy, spell);

    }

}

And the ReadScreen is simple enough.

package rltut.screens;



import rltut.Creature;

import rltut.Item;



public class ReadScreen extends InventoryBasedScreen {



    private int sx;

    private int sy;

    

    public ReadScreen(Creature player, int sx, int sy) {

        super(player);

        this.sx = sx;

        this.sy = sy;

    }



    protected String getVerb() {

        return "read";

    }



    protected boolean isAcceptable(Item item) {

        return !item.writtenSpells().isEmpty();

    }



    protected Screen use(Item item) {

        return new ReadSpellScreen(player, sx, sy, item);

    }

}

Update the PlayScreen to add spell books, map the r key to the new ReadScreen, and update the HelpScreen.

I know this is already a very long tutorial, but there's one little thing that bugs me. The creature class has some special methods that are only called when gaining a level, the gain* methods. They're only called from one place and they're small enough that we can just inline them. Eclipse, and most IDEs, can do this for you, just select the method name, right click, Refactor, Inline.

(days later....) I just realized a different, and almost certainly better, way of handling effects for each spell. Instead of each spell having a reference to an Effect and using the Effect's copy constructor, the spell class should act as an Effect factory and have an abstract newEffect method. Each individual spell would subclass Spell and implement newEffect. I'll have to do that with my next roguelike.

download the code

roguelike tutorial 18: potions and effects

2011-10-18T13:00:00.000-07:00

Let's add some potions now. When the player, or smart monster, quaffs a potion it's effect will be applied to the creature. What can we say about effects? Most effects will only last for a certain duration. Some will apply every turn or every few turns (like poison or a slow heal). Others will have a change that lasts for the duration (like confuse or resist cold). This can be done with a start method that that applies the change when first quaffed, an end method that unapplies the change when the duration has run out, and an update method that is called every turn in between. I think this will cover the basics so let's get started on them. We'll create a base Effect class and subclass it with specific effects.

package rltut;



public class Effect {

        protected int duration;

        

        public boolean isDone() { return duration < 1; }

        

        public Effect(int duration){

                this.duration = duration;

        }

        

        public void update(Creature creature){

                duration--;

        }

        

        public void start(Creature creature){

                

        }

        

        public void end(Creature creature){

                

        }

}

And add a quaffEffect to Item class.

private Effect quaffEffect;

public Effect quaffEffect() { return quaffEffect; }

public void setQuaffEffect(Effect effect) { this.quaffEffect = effect; }

Now that we've got items that can have effects when quaffed it's time to add some potions to our StuffFactory. I'll start with three simple ones that show three ways of doing things.

Here's a simple one-time potion where the work happens in the start method:

public Item newPotionOfHealth(int depth){

    Item item = new Item('!', AsciiPanel.white, "health potion");

    item.setQuaffEffect(new Effect(1){

        public void start(Creature creature){

            if (creature.hp() == creature.maxHp())

                return;

                                

            creature.modifyHp(15);

            creature.doAction("look healthier");

        }

    });

                

    world.addAtEmptyLocation(item, depth);

    return item;

}

Here is a potion that affects the creature each turn.

public Item newPotionOfPoison(int depth){

    Item item = new Item('!', AsciiPanel.white, "poison potion");

    item.setQuaffEffect(new Effect(20){

        public void start(Creature creature){

            creature.doAction("look sick");

        }

                        

        public void update(Creature creature){

            super.update(creature);

            creature.modifyHp(-1);

        }

    });

                

    world.addAtEmptyLocation(item, depth);

    return item;

}

Here's one that will affect the creature at the start and restore it at the end.

public Item newPotionOfWarrior(int depth){

    Item item = new Item('!', AsciiPanel.white, "warrior's potion");

    item.setQuaffEffect(new Effect(20){

        public void start(Creature creature){

            creature.modifyAttackValue(5);

            creature.modifyDefenseValue(5);

            creature.doAction("look stronger");

        }

        public void end(Creature creature){

            creature.modifyAttackValue(-5);

            creature.modifyDefenseValue(-5);

            creature.doAction("look less strong");

        }

    });

                

    world.addAtEmptyLocation(item, depth);

    return item;

}

And add a randomizer to help us add the new potions.

public Item randomPotion(int depth){

                switch ((int)(Math.random() * 3)){

                case 0: return newPotionOfHealth(depth);

                case 1: return newPotionOfPoison(depth);

                default: return newPotionOfWarrior(depth);

                }

        }

Now let's go back to the creature class and make sure it's calling the right methods at the right times. It will need a list of effects that are currently applied to it.

private List<Effect> effects;

public ListList<Effect> effects(){ return effects; }

Don't forget to initialize it in the creature's constructor.

Add quaff method to Creature class. Since they're so similar, the quaff and eat methods can share some code.

public void quaff(Item item){

            doAction("quaff a " + item.name());

            consume(item);

        }



        public void eat(Item item){

            doAction("eat a " + item.name());

            consume(item);

        }

        

        private void consume(Item item){

            if (item.foodValue() < 0)

                notify("Gross!");

                

            addEffect(item.quaffEffect());

                

            modifyFood(item.foodValue());

            getRidOf(item);

        }

        

        private void addEffect(Effect effect){

            if (effect == null)

                return;

                

            effect.start(this);

            effects.add(effect);

        }

Create a new method to update the effects each turn and remove any that are done. Don't forget to call the end method before removing the effect.

private void updateEffects(){

            List<Effect> done = new ArrayList<Effect>();

                

            for (Effect effect : effects){

                effect.update(this);

                if (effect.isDone()) {

                    effect.end(this);

                    done.add(effect);

                }

            }

                

            effects.removeAll(done);

        }

Call this during the creature's update method. The player can't quaff anything until we create a QuaffScreen to go with our new behavior.

package rltut.screens;



import rltut.Creature;

import rltut.Item;



public class QuaffScreen extends InventoryBasedScreen {



        public QuaffScreen(Creature player) {

                super(player);

        }



        protected String getVerb() {

                return "quaff";

        }



        protected boolean isAcceptable(Item item) {

                return item.quaffEffect() != null;

        }



        protected Screen use(Item item) {

                player.quaff(item);

                return null;

        }

}

I think I've said this before but that InventoryBasedScreen is really paying off. Now bind that to the 'q' key in the PlayScreen class and update the createItems method, also in the PlayScreen class, to add some potions. Try 3 or 4 per level to start with. Don't forget to update the HelpScreen too. Play around and change the durations or strengths or abundance of potions. Try adding some new ones that change the vision radius, heal over time, stop regeneration, consume extra food, or fill someone's stomach. I'm sure you can think of even more potions and effects. There you go; potions and effects that are simple and flexible. We're going to add a few more effects in the next tutorial when we add magic.

Wouldn't it be cool if throwing a potion at a creature caused the effect to apply to it? Easy-peasy.

private void throwAttack(Item item, Creature other) {

    commonAttack(other, attackValue / 2 + item.thrownAttackValue(), "throw a %s at the %s for %d damage", item.name(), other.name);

    other.addEffect(item.quaffEffect());

}

Then make sure the throw method removes the item if it has a quaffEffect and the target was a creature, otherwise it should add to the world like it already does. Now you can sit back and chuck poison bottles at goblins.

download the code

roguelike tutorial 17: smarter monsters

2011-10-14T13:00:00.000-07:00

Now that we've got all these nifty items and abilities, wouldn't it be cool if our cave monsters could use them too? Let's create a new creature capable of using weapons.

We can start with a GoblinAi that's almost exactly the same as the ZombieAi.

package rltut;

import java.util.List;

public class GoblinAi extends CreatureAi {
    private Creature player;

    public GoblinAi(Creature creature, Creature player) {
        super(creature);
        this.player = player;
    }

    public void onUpdate(){
        if (creature.canSee(player.x, player.y, player.z))
            hunt(player);
        else
            wander();
    }

    public void hunt(Creature target){
        List<Point> points = new Path(creature, target.x, target.y).points();
    
        int mx = points.get(0).x - creature.x;
        int my = points.get(0).y - creature.y;
    
        creature.moveBy(mx, my, 0);
    }
}

Now let's add newGoblin to the StuffFactory. Goblins start with random weapons and armor.

public Creature newGoblin(int depth, Creature player){
        Creature goblin = new Creature(world, 'g', AsciiPanel.brightGreen, "goblin", 66, 15, 5);
        goblin.equip(randomWeapon(depth));
        goblin.equip(randomArmor(depth));
        world.addAtEmptyLocation(goblin, depth);
        new GoblinAi(goblin, player);
        return goblin;
    }

Now update creature's equip method to make sure anything equipped is added to the inventory if it isn't already there.

public void equip(Item item){
        if (!inventory.contains(item)) {
            if (inventory.isFull()) {
                notify("Can't equip %s since you're holding too much stuff.", item.name());
                return;
            } else {
                world.remove(item);
                inventory.add(item);
            }
        }
    
        if (item.attackValue() == 0 && item.rangedAttackValue() == 0 && item.defenseValue() == 0)
            return;
    
        if (item.attackValue() + item.rangedAttackValue() >= item.defenseValue()){
            unequip(weapon);
            doAction("wield a " + item.name());
            weapon = item;
        } else {
            unequip(armor);
            doAction("put on a " + item.name());
            armor = item;
        }
    }

And add the missing method to the World class. This allows us to remove an object even if we don't know where it is.

public void remove(Item item) {
        for (int x = 0; x < width; x++){
            for (int y = 0; y < height; y++){
                for (int z = 0; z < depth; z++){
                if (items[x][y][z] == item) {
                    items[x][y][z] = null;
                    return;
                }
            }
        }
    }
}

We also need to make sure that when a creature dies it drops anything it was holding.

private void leaveCorpse(){
        Item corpse = new Item('%', color, name + " corpse");
        corpse.modifyFoodValue(maxHp);
        world.addAtEmptySpace(corpse, x, y, z);
        for (Item item : inventory.getItems()){
            if (item != null)
                drop(item);
            }
    }

After adding goblins to the addCreatures method of the PlayScreen you should be able to play and fight some rather tough goblins with armor and weapons of their own. Don't forget to tweak each creatures hp, attack, defense, the food values of corpses, and the xp gained or how much xp is needed for each level. You should also change the number of items and creatures per level. I prefer few items on the ground. That way the player almost has to confront goblins to get better loot.

So our goblins can use melee weapons and armor — that's nice — but they will run over and beat you with a bow instead of fire them. How about if they could throw things or fire from a distance? Time to work on the GoblinAi. My goblins will, in order of priority, try to: ranged attack, throw attack, melee attack, pickup stuff, and wander if they can't do anything else. Let's get to it.

public void onUpdate(){
        if (canRangedWeaponAttack(player))
            creature.rangedWeaponAttack(player);
        else if (canThrowAt(player))
            creature.throwItem(getWeaponToThrow(), player.x, player.y, player.z);
        else if (creature.canSee(player.x, player.y, player.z))
            hunt(player);
        else if (canPickup())
            creature.pickup();
        else
            wander();
    }

You should make your goblins do things in whatever order you want; maybe you want them to pick things up first so you could slow them down by putting some rocks or something between you.

The new helper methods are:

private boolean canRangedWeaponAttack(Creature other){
        return creature.weapon() != null
                && creature.weapon().rangedAttackValue() > 0
                && creature.canSee(other.x, other.y, other.z);
    }

    private boolean canThrowAt(Creature other) {
        return creature.canSee(other.x, other.y, other.z)
          && getWeaponToThrow() != null;
    }

    private Item getWeaponToThrow() {
        Item toThrow = null;
    
        for (Item item : creature.inventory().getItems()){
        if (item == null || creature.weapon() == item || creature.armor() == item)
            continue;
        
        if (toThrow == null || item.thrownAttackValue() > toThrow.attackValue())
            toThrow = item;
        }
    
        return toThrow;
    }

    private boolean canPickup() {
        return creature.item(creature.x, creature.y, creature.z) != null
          && !creature.inventory().isFull();
    }

It's a good idea to take these helper methods, and the hunt method, and move them up to the CreatureAi class. You can use the Pull Up refactoring in Eclipse. That way they can be used by any future creatures we add.

After adding intelligent goblins things should be much more difficult. Play test many times and tweak all the values and behavior you can.

Goblins should also see if they are holding better weapon or armor and switch to it if they are.

Here's the helper methods I came up with:

protected boolean canUseBetterEquipment() {
        int currentWeaponRating = creature.weapon() == null ? 0 : creature.weapon().attackValue() + creature.weapon().rangedAttackValue();
        int currentArmorRating = creature.armor() == null ? 0 : creature.armor().defenseValue();
    
        for (Item item : creature.inventory().getItems()){
            if (item == null)
                continue;
        
            boolean isArmor = item.attackValue() + item.rangedAttackValue() < item.defenseValue();
        
            if (item.attackValue() + item.rangedAttackValue() > currentWeaponRating
                || isArmor && item.defenseValue() > currentArmorRating)
                return true;
        }
    
        return false;
    }

protected void useBetterEquipment() {
        int currentWeaponRating = creature.weapon() == null ? 0 : creature.weapon().attackValue() + creature.weapon().rangedAttackValue();
        int currentArmorRating = creature.armor() == null ? 0 : creature.armor().defenseValue();
    
        for (Item item : creature.inventory().getItems()){
            if (item == null)
                continue;
        
            boolean isArmor = item.attackValue() + item.rangedAttackValue() < item.defenseValue();
        
            if (item.attackValue() + item.rangedAttackValue() > currentWeaponRating
                || isArmor && item.defenseValue() > currentArmorRating) {
                creature.equip(item);
            }
        }
    }

And now you have goblins that will chase you when they can, attack from afar when they can, and switch to better equipment they find. That's a monster that's more intelegent than many rogulike denizens. You can make them even more intellegent by having them remember where the player is. If they can't see the player anymore then they go to that location. This way they won't lose interest in you just because you step out of view for one turn.

These goblins are tough — sometimes too tough. It would be easier if we could regenerate some health. Add this to the creature class:

private int regenHpCooldown;
    private int regenHpPer1000;
    public void modifyRegenHpPer1000(int amount) { regenHpPer1000 += amount; }

Set the regenHpPer1000 to something reasonable in the constructor. I use 10. You could also use constructor injection or call modifyRegenHpPer1000 in our factory to make some monsters regenerate very quickly.

Then create a new method to regenerateHealth and call it as part of the update method.

private void regenerateHealth(){
        regenHpCooldown -= regenHpPer1000;
        if (regenHpCooldown < 0){
            modifyHp(1);
            modifyFood(-1);
            regenHpCooldown += 1000;
        }
    }

Since we have a new stat, we can add to our level up options too.

download the code

roguelike tutorial 16: throwing and ranged weapons

2011-10-11T13:00:00.000-07:00

Now that we've got our TargetBasedScreen let's make some more things with it. We've already got items so let's make a ThrowScreen. If we add ranged weapons then we could create a FireWeaponScreen.

First let's add another value to represent how much damage is done when an item is thrown.

private int thrownAttackValue;

    public int thrownAttackValue() { return thrownAttackValue; }

    public void modifyThrownAttackValue(int amount) { thrownAttackValue += amount; }

We can set the default to 1 in the constructor and update the StuffFactory to give a value to things that are good for throwing like certain weapons or rocks. Don't forget to update the item class's details method.

Now let's add a couple methods to the Creature class. One throws an item to a location and one damages any creature there.

public void throwItem(Item item, int wx, int wy, int wz) {

        Point end = new Point(x, y, 0);

    

        for (Point p : new Line(x, y, wx, wy)){

            if (!realTile(p.x, p.y, z).isGround())

                break;

            end = p;

        }

    

        wx = end.x;

        wy = end.y;

    

        Creature c = creature(wx, wy, wz);

    

        if (c != null)

            throwAttack(item, c);

        else

            doAction("throw a %s", item.name());

    

        unequip(item);

        inventory.remove(item);

        world.addAtEmptySpace(item, wx, wy, wz);

    }

And now actual attacks with thrown weapons. I'll add half the base attack value of the thrower since thrown weapons should generally do less damage than mele weapons.

private void throwAttack(Item item, Creature other) {

        modifyFood(-1);

    

        int amount = Math.max(0, attackValue / 2 + item.thrownAttackValue() - other.defenseValue());

    

        amount = (int)(Math.random() * amount) + 1;

    

        doAction("throw a %s at the %s for %d damage", item.name(), other.name, amount);

    

        other.modifyHp(-amount);

    

        if (other.hp < 1)

            gainXp(other);

    }

The throwing screen will be interesting because it's the first time we have a double screen scenario. We need a subclass of InventoryBasedScreen to select what we want to throw and then a subclass of a TargetBasedScreen to pick what to throw it at.

The ThrowAtScreen is simple and self explanatory. We can throw at anything we can see that isn't blocked by walls.

package rltut.screens;



import rltut.Creature;

import rltut.Item;

import rltut.Line;

import rltut.Point;



public class ThrowAtScreen extends TargetBasedScreen {

    private Item item;



    public ThrowAtScreen(Creature player, int sx, int sy, Item item) {

        super(player, "Throw " + item.name() + " at?", sx, sy);

        this.item = item;

    }



    public boolean isAcceptable(int x, int y) {

        if (!player.canSee(x, y, player.z))

            return false;

    

        for (Point p : new Line(player.x, player.y, x, y)){

            if (!player.realTile(p.x, p.y, player.z).isGround())

                return false;

        }

    

        return true;

    }



    public void selectWorldCoordinate(int x, int y, int screenX, int screenY){

        player.throwItem(item, x, y, player.z);

    }

}

The ThrowScreen is also a simple InventoryBasedScreen except we need to pass some values that aren't needed by the ThrowScreen but are used by the ThrowAtScreen.

package rltut.screens;



import rltut.Creature;

import rltut.Item;



public class ThrowScreen extends InventoryBasedScreen {

    private int sx;

    private int sy;



    public ThrowScreen(Creature player, int sx, int sy) {

        super(player);

        this.sx = sx;

        this.sy = sy;

    }



    protected String getVerb() {

        return "throw";

    }



    protected boolean isAcceptable(Item item) {

        return true;

    }



    protected Screen use(Item item) {

        return new ThrowAtScreen(player, sx, sy, item);

    }

}

Just add throwing to the HelpScreen and the respondToUserInput method of the PlayScreen and then try it.

case KeyEvent.VK_T: subscreen = new ThrowScreen(player,

        player.x - getScrollX(),

        player.y - getScrollY()); break;

Now you have a use for those rocks that are scattered around.

It's great that we can throw but how about some ranged weapons? Let's update the Item class.

private int rangedAttackValue;

    public int rangedAttackValue() { return rangedAttackValue; }

    public void modifyRangedAttackValue(int amount) { rangedAttackValue += amount; }

Anything that has a non zero rangedAttackValue is a ranged weapon. This way a weapon can have separate attack values for melee, thrown, and ranged combat. We'll keep it simple and say that ranged weapons can hit anything we can see that isn't blocked by terrain.

Add new ranged weapons to the StuffFactory. Bows are good at ranged combat but not very good at hitting things up close.

public Item newBow(int depth){

        Item item = new Item(')', AsciiPanel.yellow, "bow");

        item.modifyAttackValue(1);

        item.modifyRangedAttackValue(5);

        world.addAtEmptyLocation(item, depth);

        return item;

    }

Make sure new weapons gan be created when asking for a randomWeapon.

public Item randomWeapon(int depth){

        switch ((int)(Math.random() * 3)){

        case 0: return newDagger(depth);

        case 1: return newSword(depth);

        case 2: return newBow(depth);

        default: return newStaff(depth);

        }

    }

Creatures need a way to attack with ranged weapons. I'll add half the attack value like with thrown items.

public void rangedWeaponAttack(Creature other){

        modifyFood(-1);

    

        int amount = Math.max(0, attackValue / 2 + weapon.rangedAttackValue() - other.defenseValue());

    

        amount = (int)(Math.random() * amount) + 1;

    

        doAction("fire a %s at the %s for %d damage", weapon.name(), other.name, amount);

    

        other.modifyHp(-amount);

    

        if (other.hp < 1)

            gainXp(other);

    }

The FireWeaponScreen is similar to the ThrowAtScreen. We can fire our weapon at anything we can see that isn't blocked by walls.

package rltut.screens;



import rltut.Creature;

import rltut.Line;

import rltut.Point;



public class FireWeaponScreen extends TargetBasedScreen {



    public FireWeaponScreen(Creature player, int sx, int sy) {

        super(player, "Fire " + player.weapon().name() + " at?", sx, sy);

    }



    public boolean isAcceptable(int x, int y) {

        if (!player.canSee(x, y, player.z))

            return false;

    

        for (Point p : new Line(player.x, player.y, x, y)){

            if (!player.realTile(p.x, p.y, player.z).isGround())

                return false;

        }

    

        return true;

    }



    public void selectWorldCoordinate(int x, int y, int screenX, int screenY){

        Creature other = player.creature(x, y, player.z);

    

        if (other == null)

            player.notify("There's no one there to fire at.");

        else

            player.rangedWeaponAttack(other);

    }

}

Just add firing to the HelpScreen and the respondToUserInput method of the PlayScreen and then try it.

case KeyEvent.VK_F:

        if (player.weapon() == null || player.weapon().rangedAttackValue() == 0)

         player.notify("You don't have a ranged weapon equiped.");

        else

         subscreen = new FireWeaponScreen(player,

             player.x - getScrollX(),

             player.y - getScrollY()); break;

Creatures sometimes use up an item and it no longer exists. Other times they no longer have the item but it still exists in the world. Either way, we need to make sure they no longer have it equipped and that they no longer have it in their inventory. One way to do this is to create two helper methods and call these when possible.

private void getRidOf(Item item){

        inventory.remove(item);

        unequip(item);

    }



    private void putAt(Item item, int wx, int wy, int wz){

        inventory.remove(item);

        unequip(item);

        world.addAtEmptySpace(item, wx, wy, wz);

    }

The attack weapons all have similar bodies so we could use an Extract Method refactoring to move the commonalities to a separate method and use Extract Parameter or Parameterize Method to pass in the differences.

public void meleeAttack(Creature other){

        commonAttack(other, attackValue(), "attack the %s for %d damage", other.name);

    }



    private void throwAttack(Item item, Creature other) {

        commonAttack(other, attackValue / 2 + item.thrownAttackValue(), "throw a %s at the %s for %d damage", item.name(), other.name);

    }



    public void rangedWeaponAttack(Creature other){

        commonAttack(other, attackValue / 2 + weapon.rangedAttackValue(), "fire a %s at the %s for %d damage", weapon.name(), other.name);

    }



    private void commonAttack(Creature other, int attack, String action, Object ... params) {

        modifyFood(-2);

    

        int amount = Math.max(0, attack - other.defenseValue());

    

        amount = (int)(Math.random() * amount) + 1;

    

        Object[] params2 = new Object[params.length+1];

        for (int i = 0; i < params.length; i++){

         params2[i] = params[i];

        }

        params2[params2.length - 1] = amount;

    

        doAction(action, params2);

    

        other.modifyHp(-amount);

    

        if (other.hp < 1)

            gainXp(other);

    }

This particular implementation has the hidden side effect that the message that is passed in must end in a damage indicator since the commonAttack method will add that. It's not good to do things like this too often, but sometimes that happens.

download the code

roguelike tutorial 15: help, examine, and look screens

2011-10-07T13:00:00.000-07:00

We've got the basics of a decent game so far. Let's take some time out to add some more screens.

We'll start with the easiest, a HelpScreen.

package rltut.screens;



import java.awt.event.KeyEvent;

import asciiPanel.AsciiPanel;



public class HelpScreen implements Screen {



    public void displayOutput(AsciiPanel terminal) {

        terminal.clear();

        terminal.writeCenter("roguelike help", 1);

        terminal.write("Descend the Caves Of Slight Danger, find the lost Teddy Bear, and return to", 1, 3);

        terminal.write("the surface to win. Use what you find to avoid dying.", 1, 4);

    

        int y = 6;

        terminal.write("[g] or [,] to pick up", 2, y++);

        terminal.write("[d] to drop", 2, y++);

        terminal.write("[e] to eat", 2, y++);

        terminal.write("[w] to wear or wield", 2, y++);

        terminal.write("[?] for help", 2, y++);

        terminal.write("[x] to examine your items", 2, y++);

        terminal.write("[;] to look around", 2, y++);

    

        terminal.writeCenter("-- press any key to continue --", 22);

    }



    public Screen respondToUserInput(KeyEvent key) {

        return null;

    }

}

That's sufficient but kind of lame. I'm sure you could come up with a better story and maybe say something about what all the symbols are. Don't forget to add this new screen to the respondToUserInput method in the PlayScreen class.

Now lets make a screen that tells us details about what's in our inventory. I'll call it the ExamineScreen and map it to the x key in the PlayScreen.

package rltut.screens;



import rltut.Creature;

import rltut.Item;



public class ExamineScreen extends InventoryBasedScreen {



    public ExamineScreen(Creature player) {

        super(player);

    }



    protected String getVerb() {

        return "examine";

    }



    protected boolean isAcceptable(Item item) {

        return true;

    }



    protected Screen use(Item item) {

        String article = "aeiou".contains(item.name().subSequence(0, 1)) ? "an " : "a ";

        player.notify("It's " + article + item.name() + "." + item.details());

        return null;

    }

}

And add a details method to the Item class. You can do whatever you like but here's what I came up with:

public String details() {

    String details = "";



    if (attackValue != 0)

        details += "     attack:" + attackValue;



    if (defenseValue != 0)

        details += "     defense:" + defenseValue;



    if (foodValue != 0)

        details += "     food:" + foodValue;

    

    return details;

}

You could also display some extra description that gets passed into the item constructor.

Let's start our screen to let us look around. We'll let the user pick a tile and then tell them what it is. If you think about it, this isn't the only time the user will pick a tile through. Throwing, firing bows, and aiming spells all involve picking a tile. Since the InventoryBasedScreen has payed off so well, I think we should create a TargetBasedScreen. Let's get to it.

package rltut.screens;



import java.awt.event.KeyEvent;

import rltut.Creature;

import rltut.Line;

import rltut.Point;

import asciiPanel.AsciiPanel;



public abstract class TargetBasedScreen implements Screen {



    protected Creature player;

    protected String caption;

    private int sx;

    private int sy;

    private int x;

    private int y;



    public TargetBasedScreen(Creature player, String caption, int sx, int sy){

        this.player = player;

        this.caption = caption;

        this.sx = sx;

        this.sy = sy;

    }

}

We'll keep track of the player, a caption representing what we're targeting, the screen coordinates where the player is looking from, and the s and y offset of where we're targeting. The player and caption are protected so our subclasses can use them. Don't worry, it will make sense.

When it's time to display the output, we need to draw a line from the player to the target. I chose a line of magenta *s, but that's up to you. We also need to display the caption to the user.

public void displayOutput(AsciiPanel terminal) {

    for (Point p : new Line(sx, sy, sx + x, sy + y)){

        if (p.x < 0 || p.x >= 80 || p.y < 0 || p.y >= 24)

            continue;

        

        terminal.write('*', p.x, p.y, AsciiPanel.brightMagenta);

    }

    

    terminal.clear(' ', 0, 23, 80, 1);

    terminal.write(caption, 0, 23);

}

The user can change what's being targeted with the movement keys, select a target with Enter, or cancel with Escape. If the user tries to target something it can't, like firing out of range, then we go back to where we were targeting before.

public Screen respondToUserInput(KeyEvent key) {

        int px = x;

        int py = y;



        switch (key.getKeyCode()){

        case KeyEvent.VK_LEFT:

        case KeyEvent.VK_H: x--; break;

        case KeyEvent.VK_RIGHT:

        case KeyEvent.VK_L: x++; break;

        case KeyEvent.VK_UP:

        case KeyEvent.VK_J: y--; break;

        case KeyEvent.VK_DOWN:

        case KeyEvent.VK_K: y++; break;

        case KeyEvent.VK_Y: x--; y--; break;

        case KeyEvent.VK_U: x++; y--; break;

        case KeyEvent.VK_B: x--; y++; break;

        case KeyEvent.VK_N: x++; y++; break;

        case KeyEvent.VK_ENTER: selectWorldCoordinate(player.x + x, player.y + y, sx + x, sy + y); return null;

        case KeyEvent.VK_ESCAPE: return null;

        }

    

        if (!isAcceptable(player.x + x, player.y + y)){

            x = px;

            y = py;

        }

    

        enterWorldCoordinate(player.x + x, player.y + y, sx + x, sy + y);

    

        return this;

    }

We'll provide a simple method to determine if a tile is an acceptable target. Subclasses can override this if they want something more specific.

public boolean isAcceptable(int x, int y) {

        return true;

    }

After each time the target moves, we let subclasses do whatever they want, usually this will be to update the caption or do nothing.

public void enterWorldCoordinate(int x, int y, int screenX, int screenY) {

    }

And we do the same once the user has selected a specific location.

public void selectWorldCoordinate(int x, int y, int screenX, int screenY){

    }

This should provide a good base for any kind of targeting action.

The simplest targeting action is looking at surroundings; a LookScreen.

package rltut.screens;



import rltut.Creature;

import rltut.Item;

import rltut.Tile;



public class LookScreen extends TargetBasedScreen {



    public LookScreen(Creature player, String caption, int sx, int sy) {

        super(player, caption, sx, sy);

    }



    public void enterWorldCoordinate(int x, int y, int screenX, int screenY) {

        Creature creature = player.creature(x, y, player.z);

        if (creature != null){

            caption = creature.glyph() + " "     + creature.name() + creature.details();

            return;

        }

    

        Item item = player.item(x, y, player.z);

        if (item != null){

            caption = item.glyph() + " "     + item.name() + item.details();

            return;

        }

    

        Tile tile = player.tile(x, y, player.z);

        caption = tile.glyph() + " " + tile.details();

    }

}

This will display details to the user about whatever they are targeting. If you use this code then you'll need to create a few methods to get details about creatures and tiles. Don't forget to map it to the ';' key, or whatever key you want, in the PlayScreen.

Add a details method to the Creature class.

public String details() {

        return String.format("     level:%d     attack:%d     defense:%d     hp:%d", level, attackValue(), defenseValue(), hp);

    }

And add details to the Tile class.

FLOOR((char)250, AsciiPanel.yellow, "A dirt and rock cave floor."),

    WALL((char)177, AsciiPanel.yellow, "A dirt and rock cave wall."),

    BOUNDS('x', AsciiPanel.brightBlack, "Beyond the edge of the world."),

    STAIRS_DOWN('>', AsciiPanel.white, "A stone staircase that goes down."),

    STAIRS_UP('<', AsciiPanel.white, "A stone staircase that goes up."),

    UNKNOWN(' ', AsciiPanel.white, "(unknown)");



    private String details;

    public String details(){ return details; }



    Tile(char glyph, Color color, String details){

        this.glyph = glyph;

        this.color = color;

        this. details = details;

    }

You may have noticed a problem with the LookScreen in that you can get details about things the player can't see. Let's fix it by making some small changes to the Creature class. Basically, only return what the creature can see or remember.

public Tile realTile(int wx, int wy, int wz) {

        return world.tile(wx, wy, wz);

    }

public Tile tile(int wx, int wy, int wz) {

        if (canSee(wx, wy, wz))

            return world.tile(wx, wy, wz);

        else

            return ai.rememberedTile(wx, wy, wz);

    }

public Creature creature(int wx, int wy, int wz) {

        if (canSee(wx, wy, wz))

            return world.creature(wx, wy, wz);

        else

            return null;

    }

public Item item(int wx, int wy, int wz) {

        if (canSee(wx, wy, wz))

            return world.item(wx, wy, wz);

        else

            return null;

    }

The CreatureAi canSee method needs to use the new realTile method to avoid getting caught in an infinite recursion loop.

Here's a good-enough-for-now implementation of the CreatureAi rememberedTile method since they don't actually have a memory:

public Tile rememberedTile(int wx, int wy, int wz) {

        return Tile.UNKNOWN;

    }

And the PlayerAi override:

public Tile rememberedTile(int wx, int wy, int wz) {

        return fov.tile(wx, wy, wz);

    }

Now we've got a help screen, a way to see details about what's in our inventory, and our surroundings. Nothing very glamorous or game changing this time but it's all very helpful for the user. The TargetBasedScreen should also make future screens easier.

download the code

roguelike tutorial 14: experience and leveling up

2011-10-04T13:00:00.000-07:00

It's great that we've got some caves, equipment, and monsters but what about character development? Levels, feats, attributes, classes, and skill trees can be a complex subject worth studying but, and maybe you saw this coming, we'll do something simple to start with. For now, when a creature is killed, it's killer gains xp, when enough xp is gained, a new level is gained and some benefit is chosen. One thing I'd like to have is other creatures can gain levels too. Why? Just because I haven't seen it done before (at least not that I've noticed). It also means that positioning weak monsters between you and the big bad guy may just make the big bad guy gain levels. Maybe you should start rethinking the use of meat shields....

Our creatures need xp, a level, and a way to gain xp and levels. When the xp passes the next level threshold, the level should be incremented, the ai should get notified, and the creature should heal a bit.

private int xp;

  public int xp() { return xp; }

  public void modifyXp(int amount) {

      xp += amount;



      notify("You %s %d xp.", amount < 0 ? "lose" : "gain", amount);



      while (xp > (int)(Math.pow(level, 1.5) * 20)) {

          level++;

          doAction("advance to level %d", level);

          ai.onGainLevel();

          modifyHp(level * 2);

      }

  }



  private int level;

  public int level() { return level; }

The starting level is initialized to 1 in the constructor. I'm using a formula to determine how much experience is needed for the next level but you can use a lookup table or some other formula. Many interesting things have been said about leveling and power curves so read up, try different things, and do what works for you.

We need to update the attack method to grant experience when a creature is killed. Add the following to the end of the attack method:

if (other.hp < 1)

      gainXp(other);

Now we can grant experience based on some experience value the creature has, or on it's level, or on the killers level, or by some combination. I'm using a simple formula for now.

public void gainXp(Creature other){

    int amount = other.maxHp

      + other.attackValue()

      + other.defenseValue()

      - level * 2;



    if (amount > 0)

      modifyXp(amount);

  }

This ensures that tougher creatures are worth more and by subtracting the killer's level, easy creatures will soon be worth nothing. It's not perfect but it's simple to explain, understand, and code.

If you play it now (after creating an empty onGainLevel in CreatureAi) you should see notices about gaining levels. That's a good sign.

For this simple roguelike, when something gains a level it get's some stat bonus; increased hp, increased attack, etc. The player will be shown a list to chose from but other creatures will get one at random.

Let's create a class to represent a level up option's name and actual effect.

package rltut;



public abstract class LevelUpOption {

  private String name;

  public String name() { return name; }



  public LevelUpOption(String name){

    this.name = name;

  }



  public abstract void invoke(Creature creature);

}

We need something to track all the possible options and enforce some of our level-up logic. We'll call it a LevelUpController — even though classes with Manager or Controller in the name are usually vague and messy and not the best way to do things.

package rltut;



import java.util.ArrayList;

import java.util.List;



public class LevelUpController {



  private static LevelUpOption[] options = new LevelUpOption[]{

    new LevelUpOption("Increased hit points"){

      public void invoke(Creature creature) { creature.gainMaxHp(); }

    },

    new LevelUpOption("Increased attack value"){

      public void invoke(Creature creature) { creature.gainAttackValue(); }

    },

    new LevelUpOption("Increased defense value"){

      public void invoke(Creature creature) { creature.gainDefenseValue(); }

    },

    new LevelUpOption("Increased vision"){

      public void invoke(Creature creature) { creature.gainVision(); }

    }

  };

}

I created a few simple options based on the stats we already have but I'm sure you can come up with more. These are anonymous classes - if you're not familiar with them you should check them out. Anonymous classes can make some things very clear and succinct - other things are best left to regular classes.

This LevelUpController should be able to select one option at random and apply it to a given creature.

public void autoLevelUp(Creature creature){

    options[(int)(Math.random() * options.length)].invoke(creature);

  }

Now the CreatureAi can call this to automatically gain some benefit when a creature gains a level.

public void onGainLevel() {

    new LevelUpController().autoLevelUp(creature);

  }

Of course the Creature class needs to support these new options too. Here's what I came up with:

public void gainMaxHp() {

    maxHp += 10;

    hp += 10;

    doAction("look healthier");

  }



  public void gainAttackValue() {

    attackValue += 2;

    doAction("look stronger");

  }



  public void gainDefenseValue() {

    attackValue += 2;

    doAction("look tougher");

  }



  public void gainVision() {

    visionRadius += 1;

    doAction("look more aware");

  }

If you try it now you should see that when you gain a level you look tougher or stronger etc. You may even notice something else looking stronger or more aware. That's why I think it's so cool to have a method like doAction; you can, if you're lucky, see the rare and subtle events like these.

Try it.

What about when the player gains a level? Shouldn't we show a list of options for the user to choose from? Let's start by making sure the player doesn't automatically get free bonuses.

Override the onGainLevel method in the PlayerAi class.

public void onGainLevel(){

  }

Now we update the PlayScreen's respondToUserInput method. When we first enter the method, before the user does anything, we need to record the player's level.

int level = player.level();

After responding to the player's input, we need to see if that resulted in a level up. If so, we jump into a LevelUpScreen and tell it how many bonuses the player get's to pick.

if (player.level() > level)

      subscreen = new LevelUpScreen(player, player.level() - level);

Now all we need is a LevelUpScreen that uses a LevelUpController to show what can be picked and applies that choice.

package rltut.screens;



import java.awt.event.KeyEvent;

import java.util.List;



import rltut.Creature;

import rltut.LevelUpController;

import asciiPanel.AsciiPanel;



public class LevelUpScreen implements Screen {

  private LevelUpController controller;

  private Creature player;

  private int picks;



  public LevelUpScreen(Creature player, int picks){

    this.controller = new LevelUpController();

    this.player = player;

    this.picks = picks;

  }



  @Override

  public void displayOutput(AsciiPanel terminal) {

    List<String> options = controller.getLevelUpOptions();



    int y = 5;

    terminal.clear(' ', 5, y, 30, options.size() + 2);

    terminal.write("     Choose a level up bonus       ", 5, y++);

    terminal.write("------------------------------", 5, y++);



    for (int i = 0; i < options.size(); i++){

      terminal.write(String.format("[%d] %s", i+1, options.get(i)), 5, y++);

    }

  }



  @Override

  public Screen respondToUserInput(KeyEvent key) {

    List<String> options = controller.getLevelUpOptions();

    String chars = "";



    for (int i = 0; i < options.size(); i++){

      chars = chars + Integer.toString(i+1);

    }



    int i = chars.indexOf(key.getKeyChar());



    if (i < 0)

      return this;



    controller.getLevelUpOption(options.get(i)).invoke(player);



    if (--picks < 1)

      return null;

    else

      return this;

  }

}

And there you go; a simple leveling system that lets the player decide how they want to progress their character. You could add different bonuses like special moves, critical hits, extra xp per kill, or special abilities. You could even make it so the player could chose a new item after leveling up.

download the code

roguelike tutorial 13: aggressive monsters

2011-09-30T13:00:00.000-07:00

Now that we have all these cool weapons and armor and food, the bat's and fungi aren't as troublesome as they used to be. We need something that charges straight for us, something that peruses us relentlessly, a simple minded foe that we don't want to run into. For that we need a way to find a path to the player.

The monsters are only going to pathfind to the player if they see him so we could do the simpleist thing and move east if the player is east, north if the player is north, etc. That would almost always work well enough but let's go ahead and add real path finding. Entire tutorials are written about path finding but for this we can use the following code that implements the A Star algorithm and is specialized for our creatures:

package rltut;



import java.util.ArrayList;

import java.util.Collections;

import java.util.HashMap;



public class PathFinder {

       private ArrayList<Point> open;

       private ArrayList<Point> closed;

       private HashMap<Point, Point> parents;

       private HashMap<Point,Integer> totalCost;

     

       public PathFinder() {

             this.open = new ArrayList<Point>();

             this.closed = new ArrayList<Point>();

             this.parents = new HashMap<Point, Point>();

             this.totalCost = new HashMap<Point, Integer>();

       }

     

       private int heuristicCost(Point from, Point to) {

             return Math.max(Math.abs(from.x - to.x), Math.abs(from.y - to.y));

       }



       private int costToGetTo(Point from) {

             return parents.get(from) == null ? 0 : (1 + costToGetTo(parents.get(from)));

       }

     

       private int totalCost(Point from, Point to) {

             if (totalCost.containsKey(from))

                 return totalCost.get(from);

           

             int cost = costToGetTo(from) + heuristicCost(from, to);

             totalCost.put(from, cost);

             return cost;

       }



       private void reParent(Point child, Point parent){

             parents.put(child, parent);

             totalCost.remove(child);

       }



       public ArrayList<Point> findPath(Creature creature, Point start, Point end, int maxTries) {

             open.clear();

             closed.clear();

             parents.clear();

             totalCost.clear();

       

             open.add(start);

           

             for (int tries = 0; tries < maxTries && open.size() > 0; tries++){

                   Point closest = getClosestPoint(end);

                 

                   open.remove(closest);

                   closed.add(closest);



                   if (closest.equals(end))

                         return createPath(start, closest);

                   else

                         checkNeighbors(creature, end, closest);

             }

             return null;

       }



        private Point getClosestPoint(Point end) {

            Point closest = open.get(0);

            for (Point other : open){

                if (totalCost(other, end) < totalCost(closest, end))

                    closest = other;

            }

            return closest;

        }



        private void checkNeighbors(Creature creature, Point end, Point closest) {

            for (Point neighbor : closest.neighbors8()) {

                if (closed.contains(neighbor)

                 || !creature.canEnter(neighbor.x, neighbor.y, creature.z)

                 && !neighbor.equals(end))

                     continue;

    

                if (open.contains(neighbor))

                    reParentNeighborIfNecessary(closest, neighbor);

                else

                    reParentNeighbor(closest, neighbor);

            }

        }



        private void reParentNeighbor(Point closest, Point neighbor) {

            reParent(neighbor, closest);

            open.add(neighbor);

        }



        private void reParentNeighborIfNecessary(Point closest, Point neighbor) {

            Point originalParent = parents.get(neighbor);

            double currentCost = costToGetTo(neighbor);

            reParent(neighbor, closest);

            double reparentCost = costToGetTo(neighbor);

  

            if (reparentCost < currentCost)

                open.remove(neighbor);

            else

                reParent(neighbor, originalParent);

        }



        private ArrayList<Point> createPath(Point start, Point end) {

            ArrayList<Point> path = new ArrayList<Point>();



            while (!end.equals(start)) {

                path.add(end);

                end = parents.get(end);

            }



            Collections.reverse(path);

            return path;

        }

    }

So far I've liked having Points and Lines where all the work is done in the constructor and would like to extend this idea to Paths. So let's create a Path class that hides the details from us.

package rltut;



import java.util.List;



public class Path {



  private static PathFinder pf = new PathFinder();



  private List<Point> points;

  public List<Point> points() { return points; }



  public Path(Creature creature, int x, int y){

      points = pf.findPath(creature, 

                           new Point(creature.x, creature.y, creature.z), 

                           new Point(x, y, creature.z), 

                           300);

  }

}

If having our Line path do all that work in the constructor was questionable then this is far more questionable. I may end up regretting this and making sure future employers never see this but for now I'll try it and we'll see if it becomes a problem.

Like with our other creatures we need a CreatureAi. I'll take the easy and uncreative way out and pick Zombies for our new monster. The ZombieAi will be a bit different than the others since it needs a reference to the player so it knows who to look for.

package rltut;



import java.util.List;



public class ZombieAi extends CreatureAi {

  private Creature player;



  public ZombieAi(Creature creature, Creature player) {

    super(creature);

    this.player = player;

  }

}

During the zombie's turn it will move to the player if it can see him, otherwise it will wander around. Since zombies are a little slow, I gave them a chance of doing nothing during their turn for just a little bit of interest.

public void onUpdate(){

      if (Math.random() < 0.2)

          return;

  

      if (creature.canSee(player.x, player.y, player.z))

          hunt(player);

      else

          wander();

  }

Creating a new path each turn may not be the best idea but we'll only have a few zombies and rogulikes are turn based so it shouldn't be too much of a problem. If it does be come a performance problem we can fix it.

The hunt method finds a path to the target and moves to it.

public void hunt(Creature target){

      List<Point> points = new Path(creature, target.x, target.y).points();

  

      int mx = points.get(0).x - creature.x;

      int my = points.get(0).y - creature.y;

  

      creature.moveBy(mx, my, 0);

  }

Now we can add zombies to our factory. Since the Ai needs a reference to the player, we have to pass that in.

public Creature newZombie(int depth, Creature player){

      Creature zombie = new Creature(world, 'z', AsciiPanel.white, "zombie", 50, 10, 10);

      world.addAtEmptyLocation(zombie, depth);

      new ZombieAi(zombie, player);

      return zombie;

  }

To add zombies to our world we need to update createCreatures in the PlayScreen.

for (int i = 0; i < z + 3; i++){

         factory.newZombie(z, player);

     }

Adding pathfinding to a game is a big deal. The PathFinder we're using for now is good enough but has some major inefficiencies. I'm using a HashMap of points rather than an array so we don't have to worry about the world size or anything like that. This will take up less memory and handle aarbitrarily large maps but it will be much much slower.

download the code

roguelike tutorial 12: weapons and armor

2011-09-27T13:00:00.000-07:00

Time for some weapons and armor.

Since we have a very simple Attack value and Defense value for creatures, let's use that for our weapons and armor. Go ahead and add that to the Item class.

private int attackValue;

  public int attackValue() { return attackValue; }

  public void modifyAttackValue(int amount) { attackValue += amount; }



  private int defenseValue;

  public int defenseValue() { return defenseValue; }

  public void modifyDefenseValue(int amount) { defenseValue += amount; }

And create some new items in our factory class.

public Item newDagger(int depth){

    Item item = new Item(')', AsciiPanel.white, "dagger");

    item.modifyAttackValue(5);

    world.addAtEmptyLocation(item, depth);

    return item;

  }



  public Item newSword(int depth){

    Item item = new Item(')', AsciiPanel.brightWhite, "sword");

    item.modifyAttackValue(10);

    world.addAtEmptyLocation(item, depth);

    return item;

  }



  public Item newStaff(int depth){

    Item item = new Item(')', AsciiPanel.yellow, "staff");

    item.modifyAttackValue(5);

    item.modifyDefenseValue(3);

    world.addAtEmptyLocation(item, depth);

    return item;

  }



  public Item newLightArmor(int depth){

    Item item = new Item('[', AsciiPanel.green, "tunic");

    item.modifyDefenseValue(2);

    world.addAtEmptyLocation(item, depth);

    return item;

  }



  public Item newMediumArmor(int depth){

    Item item = new Item('[', AsciiPanel.white, "chainmail");

    item.modifyDefenseValue(4);

    world.addAtEmptyLocation(item, depth);

    return item;

  }



  public Item newHeavyArmor(int depth){

    Item item = new Item('[', AsciiPanel.brightWhite, "platemail");

    item.modifyDefenseValue(6);

    world.addAtEmptyLocation(item, depth);

    return item;

  }



  public Item randomWeapon(int depth){

    switch ((int)(Math.random() * 3)){

    case 0: return newDagger(depth);

    case 1: return newSword(depth);

    default: return newStaff(depth);

    }

  }



  public Item randomArmor(int depth){

    switch ((int)(Math.random() * 3)){

    case 0: return newLightArmor(depth);

    case 1: return newMediumArmor(depth);

    default: return newHeavyArmor(depth);

    }

  }

Don't forget to add them to the newly created game in the PlayScreen createItems method.

If you play you should be able to see them and carry them around.

If we want to use them then we need to add some methods to the creature class to equip and unequip weapons and armor. For now, creatures can wield one weapon and wear one pice of armor at a time. If you want separate armor slots for helmet, rings, shoes, etc, you can do that too. I'm also going to use the same methods to deal with armor or weapons.

private Item weapon;

  public Item weapon() { return weapon; }



  private Item armor;

  public Item armor() { return armor; }

public void unequip(Item item){

      if (item == null)

         return;

  

      if (item == armor){

          doAction("remove a " + item.name());

          armor = null;

      } else if (item == weapon) {

          doAction("put away a " + item.name());

          weapon = null;

      }

  }

public void equip(Item item){

      if (item.attackValue() == 0 && item.defenseValue() == 0)

          return;

  

      if (item.attackValue() >= item.defenseValue()){

          unequip(weapon);

          doAction("wield a " + item.name());

          weapon = item;

      } else {

          unequip(armor);

          doAction("put on a " + item.name());

          weapon = item;

      }

  }

And make sure that we unequip anything we eat or drop.

public void eat(Item item){

      if (item.foodValue() < 0)

         notify("Gross!");

  

      modifyFood(item.foodValue());

      inventory.remove(item);

      unequip(item);

  }

public void drop(Item item){

    if (world.addAtEmptySpace(item, x, y, z)){

        doAction("drop a " + item.name());

        inventory.remove(item);

        unequip(item);

    } else {

        notify("There's nowhere to drop the %s.", item.name());

    }

}

The easiest way to use our new equipment when calculating our overall attack and defense values is just to add them to the creature's getters.

public int attackValue() {

    return attackValue

     + (weapon == null ? 0 : weapon.attackValue())

     + (armor == null ? 0 : armor.attackValue());

  }



  public int defenseValue() {

    return defenseValue

     + (weapon == null ? 0 : weapon.defenseValue())

     + (armor == null ? 0 : armor.defenseValue());

  }

And now create an EquipScreen.

package rltut.screens;



import rltut.Creature;

import rltut.Item;



public class EquipScreen extends InventoryBasedScreen {



  public EquipScreen(Creature player) {

    super(player);

  }



  protected String getVerb() {

    return "wear or wield";

  }



  protected boolean isAcceptable(Item item) {

    return item.attackValue() > 0 || item.defenseValue() > 0;

  }



  protected Screen use(Item item) {

    player.equip(item);

    return null;

  }

}

Wasn't that easy?

All that's left is making the 'w' wear or wield items in the PlayScreen. I prefer having one key for both rather than one for armor and another for weapons. If you'd rather have different keys then you can do that.

case KeyEvent.VK_W: subscreen = new EquipScreen(player); break;

And now you can find and use weapons and armor. Play around with different attackValues, defenseValues, and hit points. You can have 3 or 4 weapons or 300 weapons. Try changing how abundant weapons and armor are or maybe have some more common than others.

One advantage of having all our items be the same class but have different values is that an item can be more than one thing, e.g. you could make an edible weapon and the player would be able to eat or wield it with no extra code or you could have have a weapon that increases attack and defense.

public Item newEdibleWeapon(int depth){

    Item item = new Item(')', AsciiPanel.yellow, "baguette");

    item.modifyAttackValue(3);

    item.modifyFoodValue(50);

    world.addAtEmptyLocation(item, depth);

    return item;

  }

You can't do that with Weapon, Food, and Armor subclasses.

Wouldn't it also be nice if the inventory screens told us what we have equipped so we don't eat the armor we're wearing or try to wear something we're already wearing? Here's one possible update to the InventoryBasedScreen:

String line = letters.charAt(i) + " - " + item.glyph() + " " + item.name();

    

  if(item == player.weapon() || item == player.armor())

      line += " (equipped)";

    

  lines.add(line);

Maybe the EquipScreen shouldn't let us equip what we're already using. Or maybe wearing or wielding what's already equipped should un-wear or un-weild it? That way the 'w' key can equip or unequip. It's your game so it's up to you. Implementing those is left as an exercise.

download the code

roguelike tutorial 11: hunger and food

2011-09-23T13:00:00.000-07:00

Now that we've got monsters to kill and the ability to pick up and use things, how about we add some corpses and the ability to eat them?

We first need to update our Item class to support some nutritional value.

private int foodValue;

public int foodValue() { return foodValue; }

public void modifyFoodValue(int amount) { foodValue += amount; }

And update our creature to leave corpses.

public void modifyHp(int amount) {

    hp += amount;

    if (hp < 1) {

        doAction("die");

        leaveCorpse();

        world.remove(this);

    }

}

private void leaveCorpse(){

    Item corpse = new Item('%', color, name + " corpse");

    corpse.modifyFoodValue(maxHp * 3);

    world.addAtEmptySpace(corpse, x, y, z);

}

Update creatures to also have hunger.

private int maxFood;

public int maxFood() { return maxFood; }



private int food;

public int food() { return food; }



public void modifyFood(int amount) {

    food += amount;

    if (food > maxFood) {

        food = maxFood;

    } else if (food < 1 && glyph == '@') {

        modifyHp(-1000);

    }

}

Do you see the terrible hack there? We only want the player to be able to die of starvation since it would be boring if every monster dropped dead of starvation and if they need to eat they'd have to go around killing each other. We could have an entire ecosystem of bats farming fungus, that would introduce some neat gameplay options, but that's quite a bit more complicated than I'd like to do right now. Anyway dying only if you look like a @ is still an ugly hack — a hack so ugly our children's children will feel the shame. Let's fix it right now:

public void modifyFood(int amount) {

    food += amount;

    if (food > maxFood) {

        food = maxFood;

    } else if (food < 1 && isPlayer()) {

        modifyHp(-1000);

    }

}



public boolean isPlayer(){

    return glyph == '@';

}

The hack is still there but it's isolated for now. Later if we have other creatures with an @ glyph or if the player can assume other forms, we can update this one isolated place. One thing I've learned from real life software is that although ugly hacks are inevitable, you can always isolate them so the callers don't need to deal with it.

But enough preaching, our Creatures also need a method to eat.

public void eat(Item item){

    modifyFood(item.foodValue());

    inventory.remove(item);

}

Don't forget that creatures should start with decent belly full. Add this to the creature constructor:

this.maxFood = 1000;

this.food = maxFood / 3 * 2;

Now add an EatScreen so we can eat something in our inventory.

package rltut.screens;



import rltut.Creature;

import rltut.Item;



public class EatScreen extends InventoryBasedScreen {



    public EatScreen(Creature player) {

        super(player);

    }



    protected String getVerb() {

        return "eat";

    }



    protected boolean isAcceptable(Item item) {

        return item.foodValue() != 0;

    }



    protected Screen use(Item item) {

        player.eat(item);

        return null;

    }

}

Wow, that was easy. InventoryBasedScreen is paying off already.

For the PlayScreen we need to map the 'e' key to the EatScreen.

case KeyEvent.VK_E: subscreen = new EatScreen(player); break;

We should also let the player know how hungry he is. Change the stats in displayOutput to this:

String stats = String.format(" %3d/%3d hp %8s", player.hp(), player.maxHp(), hunger());

And add a helper method. You can use whatever text and amounts you want.

private String hunger(){

    if (player.food() < player.maxFood() * 0.1)

        return "Starving";

    else if (player.food() < player.maxFood() * 0.2)

        return "Hungry";

    else if (player.food() > player.maxFood() * 0.9)

        return "Stuffed";

    else if (player.food() > player.maxFood() * 0.8)

        return "Full";

    else

        return "";

}

Of course none of this will do anything if we don't use up the food we've eaten. Go ahead and add a call to modifyFood in the relevant creature methods. Here's a couple examples:

public void dig(int wx, int wy, int wz) {

    modifyFood(-10);

    world.dig(wx, wy, wz);

    doAction("dig");

}

public void update(){

    modifyFood(-1);

    ai.onUpdate();

}

Go ahead and use the food values you want. You should play around with it for a while to decide what feels right. Maybe you want starvation to be a serious problem and hunting bats is the only way to stay alive or maybe you want starvation to hardly ever happen. Maybe heroes start with an inventory full of supplies or maybe they start with an empty and growling belly — as the designer it's up to you.

While looking at the modifyFood method I noticed we don't have prevent hp from going higher than maxHp. Even though we don't have a way to do that yet you should add a check for that.

If we eat more than the maxFood shouldn't our stomach stretch and increase our maxFood? Or maybe the user should explode from overeating? Here's my implementation:

public void modifyFood(int amount) {

    food += amount;



    if (food > maxFood) {

        maxFood = (maxFood + food) / 2;

        food = maxFood;

        notify("You can't believe your stomach can hold that much!");

        modifyHp(-1);

    } else if (food < 1 && isPlayer()) {

        modifyHp(-1000);

    }

}

It's a subtle effect but it gives the player a decision to make when full and carrying a lot of food and under the right circumstances overeating may become a useful strategy.

Now go ahead and add some food to your world. Bread, meat, apples, whatever.

download the code

roguelike tutorial 10: items, inventory, inventory screens

2011-09-20T13:00:00.000-07:00

Before we add potions, spellbooks, treasures, armor, weapons, food, and other roguelike goodies we need to think about inventory and start small. We'll need a new class for items, we'll need to update the world to track, add, and remove items, the creature class will need to be updated to pickup, use, and drop items, and the PlayScreen needs to be updated to display items and accept keystrokes to let the player actually pickup or drop items. Let's start with a new Item class.

package rltut;



import java.awt.Color;



public class Item {



    private char glyph;

    public char glyph() { return glyph; }



    private Color color;

    public Color color() { return color; }



    private String name;

    public String name() { return name; }



    public Item(char glyph, Color color, String name){

        this.glyph = glyph;

        this.color = color;

        this.name = name;

    }

}

Pretty simple so far. I didn't give it an x, y, or z coordinate because items don't need to know where they are; it kind of makes since to have them when laying on the ground but what about when they're in a container or being carried around by a creature?

I guess you could also make a Location interface. Then Point, Creature, and Item could implement it. That way an item's location could be a point in the world, a creature that's carrying it (or it's point in the world), or a container it's in. That would also be useful because an item would have a reference to wherever it is and whoever is carrying it. I'll have to try that on my next roguelike.

I guess you could have the owner update their location and add another flag indicating if the item is on the floor, in a container, or being carried. Sounds cumbersome and unnecessary; best to do without for now.

I'm happy with having a CreatureFactory to handle the details of creating a new creature so let's do the same for items. We could create an ItemFactory but I'd like to try something different: add items to the CreatureFactory. I haven't tried this before so I'm not sure if it's better to keep the two separate or not. I guess I'm going to find out.

The first step is the most powerful refactoring of all, Rename (Martin Feathers agrees: TODO). We'll rename the CreatureFactory to something more general. I'm going to just call it StuffFactory. That's an atrociously non-descriptive name but I can rename it when I think of something better — of course temporary things often stay that way so this will probably remain a StuffFactory for a while.

And now we can add our first item.

public Item newRock(int depth){

        Item rock = new Item(',', AsciiPanel.yellow, "rock");

        world.addAtEmptyLocation(rock, depth);

        return rock;

    }

Now that we have an item to put in the world, we need to extend the world class to handle that. Instead of a list of all items I'm going to try something different — I'm only going to allow one item per tile. Good idea or bad, let's go ahead with that for now.

Our world needs one item per tile.

private Item[][][] items;

This should get initialized in the constructor.

this.items = new Item[width][height][depth];

We need a way to determine what item is in a location.

public Item item(int x, int y, int z){

    return items[x][y][z];

}

And a way to add an item to a random spot similar to how we add creatures.

public void addAtEmptyLocation(Item item, int depth) {

    int x;

    int y;

    

    do {

        x = (int)(Math.random() * width);

        y = (int)(Math.random() * height);

    }

    while (!tile(x,y,depth).isGround() || item(x,y,depth) != null);

    

    items[x][y][depth] = item;

}

And lastly, we need to update our methods that are used for displaying the world to also display items.

public char glyph(int x, int y, int z){

    Creature creature = creature(x, y, z);

    if (creature != null)

        return creature.glyph();

    

    if (item(x,y,z) != null)

        return item(x,y,z).glyph();

    

    return tile(x, y, z).glyph();

}

public Color color(int x, int y, int z){

    Creature creature = creature(x, y, z);

    if (creature != null)

        return creature.color();

    

    if (item(x,y,z) != null)

        return item(x,y,z).color();

    

    return tile(x, y, z).color();

}

And the only change to the PlayScreen is to add our new rocks.

private void createItems(StuffFactory factory) {

    for (int z = 0; z < world.depth(); z++){

        for (int i = 0; i < world.width() * world.height() / 20; i++){

            factory.newRock(z);

        }

    }

}

Just call that during setup of a new game and play it.

Now that we've got a world with items in it, we need to be able to pick them up and do stuff with them.

A lot can happen with a creature's inventory so let's create another class for that. Instead of using a list I'm going to use an array so the items index doesn't change when we lose something before it. E.g. if we quaff the potion in our 'd' slot, whatever was in the 'e' slot should remain there and not slide into the 'd' slot. If you want that kind of behavior then you could use a List — it's your choice.

package rltut;



public class Inventory {



    private Item[] items;

    public Item[] getItems() { return items; }

    public Item get(int i) { return items[i]; }



    public Inventory(int max){

        items = new Item[max];

    }

}

We need a method to add an item to the first open slot in our inventory.

public void add(Item item){

    for (int i = 0; i < items.length; i++){

        if (items[i] == null){

             items[i] = item;

             break;

        }

    }

}

And a way to remove an item from our inventory.

public void remove(Item item){

    for (int i = 0; i < items.length; i++){

        if (items[i] == item){

             items[i] = null;

             return;

        }

    }

}

We also need to know if the inventory is full and we can't carry any more.

public boolean isFull(){

    int size = 0;

    for (int i = 0; i < items.length; i++){

        if (items[i] != null)

             size++;

    }

    return size == items.length;

}

Now that we've got something to represent an inventory, we can add one to our Creature class. This means that potentially any creature can have an inventory (Spoiler alert!)

private Inventory inventory;

    public Inventory inventory() { return inventory; }

We need to initialize it in the constructor. I prefer smaller inventories since that means the player can't carry half the world with them; having to chose which two swords to bring with you is more interesting than just carrying them all. I also tend to forget what I've got once it goes beyond a screenfull.

this.inventory = new Inventory(20);

And our creatures need to be able to pickup and drop stuff, moving it from the world to the creatures inventory or back.

public void pickup(){

        Item item = world.item(x, y, z);

    

        if (inventory.isFull() || item == null){

            doAction("grab at the ground");

        } else {

            doAction("pickup a %s", item.name());

            world.remove(x, y, z);

            inventory.add(item);

        }

    }

public void drop(Item item){

        doAction("drop a " + item.name());

        inventory.remove(item);

        world.addAtEmptySpace(item, x, y, z);

    }

Your IDE has probably warned you that he world class doesn't support removing and adding items so let's take care of that. Removing an item is easy:

public void remove(int x, int y, int z) {

    items[x][y][z] = null;

}

Adding an item to a specific place is more complicated since we only allow one item per tile. Because of that, we need to check adjacent tiles for an open space and repeat until we find one or run out of open spaces.

public void addAtEmptySpace(Item item, int x, int y, int z){

    if (item == null)

        return;

    

    List<Point> points = new ArrayList<Point>();

    List<Point> checked = new ArrayList<Point>();

    

    points.add(new Point(x, y, z));

    

    while (!points.isEmpty()){

        Point p = points.remove(0);

        checked.add(p);

        

        if (!tile(p.x, p.y, p.z).isGround())

            continue;

         

        if (items[p.x][p.y][p.z] == null){

            items[p.x][p.y][p.z] = item;

            Creature c = this.creature(p.x, p.y, p.z);

            if (c != null)

                c.notify("A %s lands between your feet.", item.name());

            return;

        } else {

            List<Point> neighbors = p.neighbors8();

            neighbors.removeAll(checked);

            points.addAll(neighbors);

        }

    }

}

A funky side effect of this is that if there are no open spaces then the item won't be added but will no longer be in the creature's inventory - it will vanish from the game. You can either let that happen or somehow let the caller know that it hasn't been added and shouldn't be removed from the inventory. Or you could notify everyone in viewing distance that it has vanished. I'll leave that up to you. If you leave it as it is then there's no indication that the item vanished and that may be interpreted as a bug. If you tell users it happens they probably won't consider it a bug - just part of the game. This could also make a funny scenario: imagine being trapped in a room where the floor is covered in treasure but you can't pick any up since your inventory is full and there's no room to drop your useless rusty sword.

Here's one possibility:

public void drop(Item item){

    if (world.addAtEmptySpace(item, x, y, z)){

         doAction("drop a " + item.name());

         inventory.remove(item);

    } else {

         notify("There's nowhere to drop the %s.", item.name());

    }

}

The final step is to update the PlayScreen's respondToUserInput method so the user can actually pickup things. Some roguelikes use the 'g' key to get things, some use the ',' key, and some use either one.

switch (key.getKeyChar()){

         case 'g':

         case ',': player.pickup(); break;

         case '<': player.moveBy( 0, 0, -1); break;

         case '>': player.moveBy( 0, 0, 1); break;

         }

Try it out.

We can pick up some rocks and the code is there to drop them, but we don't have a way to specify what to drop. Code that isn't being used gives me a bad feeling so let's wire up the GUI to that drop method soon. Ideally the user will press the 'd' key, the GUI will ask what to drop, the user types the letter of the thing to drop, the player drops it, and we go back to the game. Remember all that time we spent creating Screen interface and thinking about cases with different rules for user input and output? Time to make a new Screen.

Actually, if we think about what we want to do with inventory, we can do better. Here's a few scenarios off the top of my head:
press 'd', ask what to drop, the user selects something that can be dropped, drop it
press 'q', ask what to quaff, the user selects something that can be quaffed, quaff it
press 'r', ask what to read, the user selects something that can be read, read it
press 't', ask what to throw, the user selects something that can be thrown, throw it
press 'e', ask what to eat, the user selects something that can be eaten, eat it
Notice a pattern? There's a key that get's pressed, some verb (drop, quaff, read), some check against the items (droppable, quaffable, readable), and some action (drop, quaff, read). The common behavior can be put in one class called InventoryBasedScreen and the specific details can be in subclasses. That way we can have a DropScreen, QuaffScreen, ReadScreen and others that all subclass the InventoryBasedScreen and just provide a few simple details.

Let's start with a basic InventoryBasedScreen:

package rltut.screens;



import java.awt.event.KeyEvent;

import java.util.ArrayList;

import rltut.Creature;

import rltut.Item;

import asciiPanel.AsciiPanel;



public abstract class InventoryBasedScreen implements Screen {



    protected Creature player;

    private String letters;



    protected abstract String getVerb();

    protected abstract boolean isAcceptable(Item item);

    protected abstract Screen use(Item item);



    public InventoryBasedScreen(Creature player){

        this.player = player;

        this.letters = "abcdefghijklmnopqrstuvwxyz";

    }

}

We need the reference to the player because that's the one who's going to do the work of dropping, quaffing, eating, etc. It's protected so that the subclasses can use it. The letters are so we can assign a letter to each inventory slot (If you allow the inventory to be larger then you need to add more characters). Maybe this should be part of the inventory class but I think this is the only place where we will use it so I'll put it here for now. We've also got abstract methods so our subclasses can specify the verb, what items are acceptable for the action, and a method to actually perform the action. Using an item returns a Screen since it may lead to a different screen, e.g. if we're going to throw something then we can transition into some sort of targeting screen.

Since this is a screen it needs to actually display some output. We not only ask what they want to use but go ahead and show a list of acceptable items.

public void displayOutput(AsciiPanel terminal) {

        ArrayList<String> lines = getList();

    

        int y = 23 - lines.size();

        int x = 4;



        if (lines.size() > 0)

            terminal.clear(' ', x, y, 20, lines.size());

    

        for (String line : lines){

            terminal.write(line, x, y++);

        }

    

        terminal.clear(' ', 0, 23, 80, 1);

        terminal.write("What would you like to " + getVerb() + "?", 2, 23);

    

        terminal.repaint();

    }

That should be pretty clear: write the list in the lower left hand corner and ask the user what to do. If you allow a larger inventory then you'll have to show two columns or scroll the list or something.

The getList method will make a list of all the acceptable items and the letter for each corresponding inventory slot.

private ArrayList<String> getList() {

        ArrayList<String> lines = new ArrayList<String>();

        Item[] inventory = player.inventory().getItems();

    

        for (int i = 0; i < inventory.length; i++){

            Item item = inventory[i];

        

            if (item == null || !isAcceptable(item))

                continue;

        

            String line = letters.charAt(i) + " - " + item.glyph() + " " + item.name();

        

            lines.add(line);

        }

        return lines;

    }

Now that we've got some output we need to respond to user input. The user can press escape to go back to playing the game, select a valid character to use, or some invalid key that will do nothing and keep them on the current screen.

public Screen respondToUserInput(KeyEvent key) {

        char c = key.getKeyChar();



        Item[] items = player.inventory().getItems();

    

        if (letters.indexOf(c) > -1

             && items.length > letters.indexOf(c)

             && items[letters.indexOf(c)] != null

             && isAcceptable(items[letters.indexOf(c)]))

            return use(items[letters.indexOf(c)]);

        else if (key.getKeyCode() == KeyEvent.VK_ESCAPE)

            return null;

        else

            return this;

    }

I hope that little mess makes sense. Use it, exit, or ask again.

This doesn't do anything yet, in fact it's an abstract class so it can't do anything until we create a subclass and use that. The first subclass will be a DropScreen.

package rltut.screens;



import rltut.Creature;

import rltut.Item;



public class DropScreen extends InventoryBasedScreen {



    public DropScreen(Creature player) {

        super(player);

    }

}

We just need to supply the methods that were abstract in the original. We're asking the use what they want to drop so the getVerb should return that.

protected String getVerb() {

        return "drop";

    }

Since anything can be dropped, all items are acceptable.

protected boolean isAcceptable(Item item) {

        return true;

    }

Once the user selects what to drop we tell the player to do the work and return null since we are done with the DropScreen.

protected Screen use(Item item) {

        player.drop(item);

        return null;

    }

Now we can update the PlayScreen to use our fancy new DropScreen. The DropScreen is a little different that the start, play, win, and lose screens since it needs to return to the PlayScreen once it's done. We could pass the current play screen into newly created DropScreen and have it return the PlayScreen when it's done, but I've tried that before and it became kind of messy. This time I'll try something different. We can have the PlayScreen know if we're working with another sub screen and delegate input and output to that screen screen. Once the subscreen is done, it get's set to null and the PlayScreen works as normal.

First the PlayScreen needs to know what the subscreen is. If it's null then everything should work as it did before. There's no need to initialize this since we check for nulls when we use it.

private Screen subscreen;

After we displayOutput the subscreen should get a chance to display. This way the current game world will be a background to whatever the subscreen wants to show.

if (subscreen != null)

    subscreen.displayOutput(terminal);

And any user input needs to be sent to the subscreen if it exists. The subscreen will also tell the PlayScreen what the new subscreen is. We also need to handle the users pressing the 'd' key to drop items from inventory. Lastly, if we should update the world only if we don't have a subscreen.

public Screen respondToUserInput(KeyEvent key) {

     if (subscreen != null) {

         subscreen = subscreen.respondToUserInput(key);

     } else {

         switch (key.getKeyCode()){

         case KeyEvent.VK_ESCAPE: return new LoseScreen();

         case KeyEvent.VK_ENTER: return new WinScreen();

         case KeyEvent.VK_LEFT:

         case KeyEvent.VK_H: player.moveBy(-1, 0, 0); break;

         case KeyEvent.VK_RIGHT:

         case KeyEvent.VK_L: player.moveBy( 1, 0, 0); break;

         case KeyEvent.VK_UP:

         case KeyEvent.VK_K: player.moveBy( 0,-1, 0); break;

         case KeyEvent.VK_DOWN:

         case KeyEvent.VK_J: player.moveBy( 0, 1, 0); break;

         case KeyEvent.VK_Y: player.moveBy(-1,-1, 0); break;

         case KeyEvent.VK_U: player.moveBy( 1,-1, 0); break;

         case KeyEvent.VK_B: player.moveBy(-1, 1, 0); break;

         case KeyEvent.VK_N: player.moveBy( 1, 1, 0); break;

         case KeyEvent.VK_D: subscreen = new DropScreen(player); break;

         }

        

         switch (key.getKeyChar()){

         case 'g':

         case ',': player.pickup(); break;

         case '<': player.moveBy( 0, 0, -1); break;

         case '>': player.moveBy( 0, 0, 1); break;

         }

     }

    

     if (subscreen == null)

         world.update();

    

     if (player.hp() < 1)

         return new LoseScreen();

    

     return this;

 }

That was a lot of little changes to a few different places but if the DropScreen is any indication, the InventoryBasedScreen should be a major win in terms of being able to implement new features with little effort. The PlayScreen is getting a little out of hand now that it creates a new world, displays the world, handles user commands and deals with subscreens. Maybe the part about setting up a new game should be moved somewhere else.

Let's make this a proper roguelike with a special object to retrieve and return to the surface with. This will also give the player a legitimate victory condition other than pressing enter.

Add our new item to the SuffFactory:

public Item newVictoryItem(int depth){

        Item item = new Item('*', AsciiPanel.brightWhite, "teddy bear");

        world.addAtEmptyLocation(item, depth);

        return item;

    }

And make sure it get's created when we start a new game:

private void createItems(StuffFactory factory) {

    for (int z = 0; z < world.depth(); z++){

        for (int i = 0; i < world.width() * world.height() / 20; i++){

            factory.newRock(z);

        }

    }

    factory.newVictoryItem(world.depth() - 1);

}

And update the WorldBuilder to include some exist stairs.

private WorldBuilder addExitStairs() {

        int x = -1;

        int y = -1;

    

        do {

            x = (int)(Math.random() * width);

            y = (int)(Math.random() * height);

        }

        while (tiles[x][y][0] != Tile.FLOOR);

    

        tiles[x][y][0] = Tile.STAIRS_UP;

        return this;

    }

And make that part of creating caves.

public WorldBuilder makeCaves() {

        return randomizeTiles()

             .smooth(8)

             .createRegions()

             .connectRegions()

             .addExitStairs();

    }

Our normal stair handling won't work with up stairs on the uppermost layer of the world so let's handle that in the PlayScreen.

switch (key.getKeyChar()){

    case 'g':

    case ',': player.pickup(); break;

    case '<':

        if (userIsTryingToExit())

         return userExits();

        else

         player.moveBy( 0, 0, -1); 

        break;

    case '>': player.moveBy( 0, 0, 1); break;

    }

private boolean userIsTryingToExit(){

    return player.z == 0 && world.tile(player.x, player.y, player.z) == Tile.STAIRS_UP;

}

private Screen userExits(){

    for (Item item : player.inventory().getItems()){

        if (item != null && item.name().equals("teddy bear"))

            return new WinScreen();

    }

    return new LoseScreen();

}

Now you can remove the cases for VK_ESCAPE and VK_ENTER. You can also remove the message about pressing escape or enter. It took half the tutorials but we finally have a victory condition.

download the code

roguelike tutorial 09: wandering monsters

2011-09-16T13:00:00.000-07:00

We need some monsters to wander around our caves. How about some fast moving bats?

First let's add some default movement behavior to the CreatureAi.

public void onEnter(int x, int y, int z, Tile tile){

    if (tile.isGround()){

         creature.x = x;

         creature.y = y;

         creature.z = z;

    } else {

         creature.doAction("bump into a wall");

    }

}

Let's also give it a method of moving randomly. This common behavior can be called by any subclass.

public void wander(){

    int mx = (int)(Math.random() * 3) - 1;

    int my = (int)(Math.random() * 3) - 1;

    creature.moveBy(mx, my, 0);

}

Now the ai for our bats.

package rltut;



public class BatAi extends CreatureAi {



    public BatAi(Creature creature) {

        super(creature);

    }



    public void onUpdate(){

        wander();

        wander();

    }

}

We could set up a system for dealing with different monster speeds but this is simple enough: bats move twice for every one of your moves. Easy to implement, easy to understand.

Now we add bats to our CreatureFactory. I picked some low hp and attack so they could nibble on you a bit but shouldn't be too much of a problem.

public Creature newBat(int depth){

    Creature bat = new Creature(world, 'b', AsciiPanel.yellow, 15, 5, 0);

    world.addAtEmptyLocation(bat, depth);

    new BatAi(bat);

    return bat;

}

And in our PlayScreen we need to update createCreatures. How about 20 bats per level?

for (int i = 0; i < 20; i++){

    creatureFactory.newBat(z);

}

And now that our player is in some danger of being killed, let's add a check after the world get's updated.

if (player.hp() < 1)

    return new LoseScreen();

Try it out. You should see bats being flying about and being batty.

If you run this you'll soon notice that the bats drop dead from attacking each other or even attacking themselves. Suicide bats are funny but they quickly go extinct.

Let's add a check to the first line of the moveBy method in the Creature class. It should bail out early if we're not actually moving. This will take care of creatures killing themselves when all they want to do is stand in one place.

if (mx==0 && my==0 && mz==0)

    return;

Creatures should also be able to see what other creatures are in the world so the CreatureAi can know what's going on.

public Creature creature(int wx, int wy, int wz) {

    return world.creature(wx, wy, wz);

}

We can now improve the CreatureAi wander method to make sure creatures don't fight other's like them.

public void wander(){

    int mx = (int)(Math.random() * 3) - 1;

    int my = (int)(Math.random() * 3) - 1;

    

    Creature other = creature.creature(creature.x + mx, creature.y + my, creature.z);

    

    if (other != null && other.glyph() == creature.glyph())

        return;

    else

        creature.moveBy(mx, my, 0);

}

You could also make it keep trying until mx != 0 && my != 0, that way it would never stand in the same spot. You may want to make sure it doesn't try to move into a wall or make it able to go up or down stairs.

And there you go. You now have some deep and bat-filled caves to explore.

Using the glyph in messages is lame; Creatures should have a name.

private String name;

    public String name() { return name; }

Using constructor injection, update the creatureFactory to pass in the appropriate name. Finally, update any messages that used the creature's glyph to now use the creature's name.

Much better.

download the code

roguelike tutorial 08: vision, line of sight, and field of view

2011-09-13T13:00:00.000-07:00

It doesn't feel like we're exploring much since we see the whole level from the beginning. Ideally we can only see our immediate surroundings and remember what we've already seen. I think we can do that in one session.

The first thing we need is a way to determine if something is in our line of sight. To do this we get all the points in between us and what we want to look at and see if any of them block our vision. For this, we can create a new Line class that uses Bresenham's line algorithm to find all the points along the line.

package rltut;



import java.util.ArrayList;

import java.util.Iterator;

import java.util.List;



public class Line {

    private List<Point> points;

    public List<Point> getPoints() { return points; }



    public Line(int x0, int y0, int x1, int y1) {

        points = new ArrayList<Point>();

    

        int dx = Math.abs(x1-x0);

        int dy = Math.abs(y1-y0);

    

        int sx = x0 < x1 ? 1 : -1;

        int sy = y0 < y1 ? 1 : -1;

        int err = dx-dy;

    

        while (true){

            points.add(new Point(x0, y0, 0));

        

            if (x0==x1 && y0==y1)

                break;

        

            int e2 = err * 2;

            if (e2 > -dx) {

                err -= dy;

                x0 += sx;

            }

            if (e2 < dx){

                err += dx;

                y0 += sy;

            }

        }

    }

}

If you look this all the work is done in the constructor - that's a bad sign. So says Misko Hevery of Google fame, Martian Feathers of Working Effectively With Legacy Code, and anyone who's had to deal with this before. On the other hand, it doesn't do that much work; it just creates a list of points. The points are value objects and the line itself could be a value object. I'm certainly no fan of constructors that initialize their collaborators but this seems like a special case. Since it's just a personal project and no one's life or money are on the line, I'll try it and see if it becomes a problem.

To make things a tiny bit more convenient to loop through the points in a line, we can make the class implement Iterable<Point>. All we have to do is declare that the Line implements Iterable<Point> and add the following method:

public Iterator<Point> iterator() {

        return points.iterator();

    }

I have a feeling that we will use this Line class a lot as we add more features.

Since creatures are the ones who are doing the seeing, it makes since to give creatures a new stat to say how far they can see and a couple methods for looking at the world.

private int visionRadius;

    public int visionRadius() { return visionRadius; }



    public boolean canSee(int wx, int wy, int wz){

        return ai.canSee(wx, wy, wz);

    }



    public Tile tile(int wx, int wy, int wz) {

        return world.tile(wx, wy, wz);

    }

I set the vision radius to 9 in the creature's constructor but you should use whatever value you prefer or even have it passed in from the creatureFactory. Since we delegate the task to seeing to the CreatureAi, that's where the work is done and what we'll add to next.

public boolean canSee(int wx, int wy, int wz) {

        if (creature.z != wz)

            return false;

    

        if ((creature.x-wx)*(creature.x-wx) + (creature.y-wy)*(creature.y-wy) > creature.visionRadius()*creature.visionRadius())

            return false;

    

        for (Point p : new Line(creature.x, creature.y, wx, wy)){

            if (creature.tile(p.x, p.y, wz).isGround() || p.x == wx && p.y == wy)

                continue;

        

            return false;

        }

    

        return true;

    }

Now that our player can see his immediate surroundings, we should update the PlayScreen to only show the monsters and tiles that can be seen. Tiles outside the line of sight are shown in dark grey.

private void displayTiles(AsciiPanel terminal, int left, int top) {

     for (int x = 0; x < screenWidth; x++){

         for (int y = 0; y < screenHeight; y++){

             int wx = x + left;

             int wy = y + top;



             if (player.canSee(wx, wy, player.z)){

                 Creature creature = world.creature(wx, wy, player.z);

                 if (creature != null)

                     terminal.write(creature.glyph(), creature.x - left, creature.y - top, creature.color());

                 else

                     terminal.write(world.glyph(wx, wy, player.z), x, y, world.color(wx, wy, player.z));

             } else {

                 terminal.write(world.glyph(wx, wy, player.z), x, y, Color.darkGray);

             }

         }

     }

 }

Try it. You should see tiles outside of the player's range in a dark grey color.

We need a place to store what tiles the user has seen but who tracks what's been seen? It's part of the GUI so maybe the PlayScreen? But it's heavely based on the map so maybe the World class should flag tiles that have been seen — many games do this so maybe we should too? But the Creature is the one seeing so maybe it should. But we want the player to record this, the other monsters don't need to so maybe the CreatureAi should track what the creature has seen? That last one seems right to me; the PlayerAi should track what the player has seen and the PlayScreen should use that info to determines what get's displayed. This also means that we can store what tile the player saw at each location so what the player remembers may be different than what is in the real world. So if there's a cave in, or tunnels are dug, or some other change in the world then the player will remember what was last seen and be quite surprised when returning to that area. Neat posiblities.

We need a new tile to indicate a place that has not been seen. This is similar to the out of bounds tile we have since it's not really part of the world but it makes things much easier.

UNKNOWN(' ', AsciiPanel.white)

There are several different ways of determining what is in the player's field of view this but the simplest, and therefore what I prefer, is called raycasting. It's exactly what we're already doing: draw a line from the viewer to the tile in question to see if anything is blocking the vision. Raycasting is probably the slowest way, but it's quick enough and I think has the best overall look. Other methods perform differently when columns and doorways are involved.

Let's create a new class for our field of view. We can slightly extend the common definition of ours to not only determine what is in view but to remember what has already been seen too. What's visible now and what was seen earlier are technically two different things and possibly should be implemented by two different classes, but they're close enough and we can change it later if necessary.

package rltut;



public class FieldOfView {

    private World world;

    private int depth;



    private boolean[][] visible;

    public boolean isVisible(int x, int y, int z){

        return z == depth && x >= 0 && y >= 0 && x < visible.length && y < visible[0].length && visible[x][y];

    }



    private Tile[][][] tiles;

    public Tile tile(int x, int y, int z){

        return tiles[x][y][z];

    }



    public FieldOfView(World world){

        this.world = world;

        this.visible = new boolean[world.width()][world.height()];

        this.tiles = new Tile[world.width()][world.height()][world.depth()];

    

        for (int x = 0; x < world.width(); x++){

            for (int y = 0; y < world.height(); y++){

                for (int z = 0; z < world.depth(); z++){

                    tiles[x][y][z] = Tile.UNKNOWN;

                }

            }

        }

    }

}

That seems like a good interface. We can ask if a tile is visible and we can ask what tile was last seen somewhere. We just need to add the method to update what's visible and has been seen.

public void update(int wx, int wy, int wz, int r){

        depth = wz;

        visible = new boolean[world.width()][world.height()];

    

        for (int x = -r; x < r; x++){

            for (int y = -r; y < r; y++){

                if (x*x + y*y > r*r)

                    continue;

         

                if (wx + x < 0 || wx + x >= world.width() 

                 || wy + y < 0 || wy + y >= world.height())

                    continue;

         

                for (Point p : new Line(wx, wy, wx + x, wy + y)){

                    Tile tile = world.tile(p.x, p.y, wz);

                    visible[p.x][p.y] = true;

                    tiles[p.x][p.y][wz] = tile;

             

                    if (!tile.isGround())

                        break;

                }

            }

        }

    }

Only the player is going to use this advanced field of view, all other creatures can use the default line of sight code. Add a FieldOfView variable to the PlayerAi and override the canSee method.

public boolean canSee(int wx, int wy, int wz) {

    return fov.isVisible(wx, wy, wz);

}

Since the FieldOfView requires a world to be passed in the constructor and we don't want the ai's to know about the world, we can build the FieldOfView elseware and rely on constructor injection to give it to the PlayerAi. This means it will have to be passed into the CreatureFactory from the PlayScreen too.

The PlayScreen should construct a new field of view once the world has been made and pass it to the CreatureFactory. Since the PlayScreen is also responsible for displaying the world to the user, we should keep a reference to the field of view. Then we can update it before displaying the world and rely on it for tiles outside of the player's view. After that, we just need to modify the displayTiles method.

private void displayTiles(AsciiPanel terminal, int left, int top) {

        fov.update(player.x, player.y, player.z, player.visionRadius());

    

        for (int x = 0; x < screenWidth; x++){

         for (int y = 0; y < screenHeight; y++){

             int wx = x + left;

             int wy = y + top;



             if (player.canSee(wx, wy, player.z)){

                 Creature creature = world.creature(wx, wy, player.z);

                 if (creature != null)

                     terminal.write(creature.glyph(), creature.x - left, creature.y - top, creature.color());

                 else

                     terminal.write(world.glyph(wx, wy, player.z), x, y, world.color(wx, wy, player.z));

                 else

                     terminal.write(fov.tile(wx, wy, player.z).glyph(), x, y, Color.darkGray);

             }

        }

    }

}

And there you go, line of sight and field of view. These caves are starting to feel like real caves. If only they had some more monsters....

I just remembered something I wanted to do with the world once we added creatures. Replace the glyph and color methods with these:

public char glyph(int x, int y, int z){

    Creature creature = creature(x, y, z);

    return creature != null ? creature.glyph() : tile(x, y, z).glyph();

}

public Color color(int x, int y, int z){

    Creature creature = creature(x, y, z);

    return creature != null ? creature.color() : tile(x, y, z).color();

}

Since the world takes care of that for us, the PlayScreen becomes simpler.

private void displayTiles(AsciiPanel terminal, int left, int top) {

    fov.update(player.x, player.y, player.z, player.visionRadius());

    

    for (int x = 0; x < screenWidth; x++){

        for (int y = 0; y < screenHeight; y++){

            int wx = x + left;

            int wy = y + top;



            if (player.canSee(wx, wy, player.z))

                terminal.write(world.glyph(wx, wy, player.z), x, y, world.color(wx, wy, player.z));

            else

                terminal.write(fov.tile(wx, wy, player.z).glyph(), x, y, Color.darkGray);

        }

    }

}

Instead of having doAction notify everyone nearby, it should only notify them if they can see the one doing the action.

public void doAction(String message, Object ... params){

    int r = 9;

    for (int ox = -r; ox < r+1; ox++){

        for (int oy = -r; oy < r+1; oy++){

            if (ox*ox + oy*oy > r*r)

                continue;

         

            Creature other = world.creature(x+ox, y+oy, z);

         

            if (other == null)

                continue;

         

            if (other == this)

                other.notify("You " + message + ".", params);

            else if (other.canSee(x, y, z))

                other.notify(String.format("The %s %s.", name, makeSecondPerson(message)), params);

         }

    }

}

Now you have to actually see something happen in order to be notified about it.

download the code

roguelike tutorial 07: z levels and deeper caves

2011-09-09T13:00:00.000-07:00

Our simple little roguelike is so flat and two dimensional. Let's change that. I'll try to write use code thats easy to read and understand, even if it's woefully inefficient. It's a good thing world gen only happens once.

Most roguelikes have a 2d level and just simulate the current one. When you leave the current level either a new one is created or an old one is loaded. If loading an old level then the program usually simulates the passage of time and adds some items or creatures and makes it look like things happened even though you weren't there. I find it easier just to create the entire world at once and simulate everything. This also makes world gen easier since you can make decisions based on the entire world, not just the thin slices that already exist. Our world is small enough for now that the extra time to create it and memory it takes up it shouldn't be a problem.

In order to build better caves we're going to have to work with coordinates a lot. We should make a class to represent a point in space.

package rltut;



import java.util.ArrayList;

import java.util.Collections;

import java.util.List;



public class Point {

    public int x;

    public int y;

    public int z;



    public Point(int x, int y, int z){

        this.x = x;

        this.y = y;

        this.z = z;

    }

}

Two points that represent the same location should be treated as equal. These are known as value objects as opposed to reference objects. We can tell Java that by overriding the hashCode and equals methods. Here's what Eclipse generated:

@Override

    public int hashCode() {

        final int prime = 31;

        int result = 1;

        result = prime * result + x;

        result = prime * result + y;

        result = prime * result + z;

        return result;

    }



    @Override

    public boolean equals(Object obj) {

        if (this == obj)

         return true;

        if (obj == null)

         return false;

        if (!(obj instanceof Point))

         return false;

        Point other = (Point) obj;

        if (x != other.x)

         return false;

        if (y != other.y)

         return false;

        if (z != other.z)

         return false;

        return true;

    }

We're also going to spend a lot of time working with points that are adjacent to something. This will be much easier if we can just ask a point for a list of it's eight neighbors.

public List<point> neighbors8(){

    List<point> points = new ArrayList<point>();

  

    for (int ox = -1; ox < 2; ox++){

        for (int oy = -1; oy < 2; oy++){

            if (ox == 0 && oy == 0)

                continue;

    

            points.add(new Point(x+ox, y+oy, z));

        }

    }



    Collections.shuffle(points);

    return points;

}

We shuffle the list before returning it so we don't introduce bias. Otherwise the upper left neighbor would always be checked first and the lower right would be last which may lead to some odd things. Now that we have a Point class, let's use it to make some better caves. First we need to add two new tile types, stairs up and stairs down.

STAIRS_DOWN('>', AsciiPanel.white),

    STAIRS_UP('<', AsciiPanel.white);

Then, in the WorldBuilder class, we create a region map. Each location has a number that identifies what region of contiguous open space it belongs to; i.e. if two locations have the same region number, then you can walk from one to the other without digging through walls.

private WorldBuilder createRegions(){

        regions = new int[width][height][depth];

    

        for (int z = 0; z < depth; z++){

            for (int x = 0; x < width; x++){

                for (int y = 0; y < height; y++){

                   if (tiles[x][y][z] != Tile.WALL && regions[x][y][z] == 0){

                       int size = fillRegion(nextRegion++, x, y, z);

              

                       if (size < 25)

                           removeRegion(nextRegion - 1, z);

                   }

                }

            }

        }

        return this;

    }

This will look at every space in the world. If it is not a wall and it does not have a region assigned then that empty space, and all empty spaces it's connected to, will be given a new region number. If the region is to small it gets removed. When this method is done, all open tiles will have a region assigned to it and we can use the regions array to see if two tiles are part of the same open space.

The removeRegion method does what it sounds like. It just zero's out the region number and fills in the cave so it's solid wall. I prefer caves where the smaller areas have been filled in but this step isn't necessary.

private void removeRegion(int region, int z){

    for (int x = 0; x < width; x++){

        for (int y = 0; y < height; y++){

            if (regions[x][y][z] == region){

                regions[x][y][z] = 0;

                tiles[x][y][z] = Tile.WALL;

            }

        }

    }

}

The fillRegion method does a flood-fill starting with an open tile. It, and any open tile it's connected to, gets assigned the same region number. This is repeated until there are no unassigned empty neighboring tiles.

private int fillRegion(int region, int x, int y, int z) {

        int size = 1;

        ArrayList<Point> open = new ArrayList<Point>();

        open.add(new Point(x,y,z));

        regions[x][y][z] = region;

    

        while (!open.isEmpty()){

            Point p = open.remove(0);



            for (Point neighbor : p.neighbors8()){

                if (regions[neighbor.x][neighbor.y][neighbor.z] > 0

                  || tiles[neighbor.x][neighbor.y][neighbor.z] == Tile.WALL)

                    continue;



                size++;

                regions[neighbor.x][neighbor.y][neighbor.z] = region;

                open.add(neighbor);

            }

        }

        return size;

    }

To connect all the regions with stairs we just start at the top and connect them one layer at a time.

public WorldBuilder connectRegions(){

        for (int z = 0; z < depth-1; z++){

            connectRegionsDown(z);

        }

        return this;

    }

To connect two adjacent layers we look at each region that sits above another region. If they haven't been connected then we connect them.

private void connectRegionsDown(int z){

    List<String> connected = new ArrayList<String>();

  

    for (int x = 0; x < width; x++){

        for (int y = 0; y < height; y++){

            String region = regions[x][y][z] + "," + regions[x][y][z+1];

            if (tiles[x][y][z] == Tile.FLOOR

              && tiles[x][y][z+1] == Tile.FLOOR

              && !connected.contains(region)){

                connected.add(region);

                connectRegionsDown(z, regions[x][y][z], regions[x][y][z+1]);

            }

        }

    }

}

The region variable is just a way to uniquely combine two numbers into one. This way we just need a list of the region strings instead of some list of pairs or something. If java had tuples then we could use that instead of this way.

To connect two regions, we get a list of all the locations where one is directly above the other. Then, based on how much area overlaps, we connect them with stairs going up and stairs going down.

private void connectRegionsDown(int z, int r1, int r2){

        List<Point> candidates = findRegionOverlaps(z, r1, r2);

    

        int stairs = 0;

        do{

            Point p = candidates.remove(0);

            tiles[p.x][p.y][z] = Tile.STAIRS_DOWN;

            tiles[p.x][p.y][z+1] = Tile.STAIRS_UP;

            stairs++;

        }

        while (candidates.size() / stairs > 250);

    }

Finding which locations of two regions overlap is pretty straight forward.

public List<Point> findRegionOverlaps(int z, int r1, int r2) {

        ArrayList<Point> candidates = new ArrayList<Point>();

    

        for (int x = 0; x < width; x++){

         for (int y = 0; y < height; y++){

             if (tiles[x][y][z] == Tile.FLOOR

                  && tiles[x][y][z+1] == Tile.FLOOR

                  && regions[x][y][z] == r1

                  && regions[x][y][z+1] == r2){

              candidates.add(new Point(x,y,z));

             }

         }

        }

    

        Collections.shuffle(candidates);

        return candidates;

    }

After all that, the method for making caves needs to be amended.

public WorldBuilder makeCaves() {

        return randomizeTiles()

             .smooth(8)

             .createRegions()

             .connectRegions();

    }

The world class obviously needs to be changed. Not only does a third layer need to be added to the tiles array, but most methods need to accept a new z parameter. I'm suer you can find all the changes that need to be made. Here's an example of an updated method:

public void addAtEmptyLocation(Creature creature, int z){

        int x;

        int y;

    

        do {

         x = (int)(Math.random() * width);

         y = (int)(Math.random() * height);

        }

        while (!tile(x,y,z).isGround() || creature(x,y,z) != null);

    

        creature.x = x;

        creature.y = y;

        creature.z = z;

        creatures.add(creature);

    }

The Creature class also needs a new z coordinate and many of it's methods need to be updated too. I'll leave that to you as well. Here's my new version of the moveBy method.

public void moveBy(int mx, int my, int mz){

        Tile tile = world.tile(x+mx, y+my, z+mz);

    

        if (mz == -1){

            if (tile == Tile.STAIRS_DOWN) {

                doAction("walk up the stairs to level %d", z+mz+1);

            } else {

                doAction("try to go up but are stopped by the cave ceiling");

                return;

            }

        } else if (mz == 1){

            if (tile == Tile.STAIRS_UP) {

                doAction("walk down the stairs to level %d", z+mz+1);

            } else {

                doAction("try to go down but are stopped by the cave floor");

                return;

            }

        }

    

        Creature other = world.creature(x+mx, y+my, z+mz);

    

        if (other == null)

            ai.onEnter(x+mx, y+my, z+mz, tile);

        else

            attack(other);

    }

The CreatureAi classes, PlayScreen class, and a few others need to be updated. Your IDE should tell you which ones are broken by the new thrid dimension. You should be able to fix all of these on your own. One thing is that the greater than and less than keys used to move up and down stairs don't work with the keyCode() method so that needs to be handled differently. Here's how I did it:

switch (key.getKeyChar()){

        case '<': player.moveBy( 0, 0, -1); break;

        case '>': player.moveBy( 0, 0, 1); break;

        }

This one was a lot of work. The algorithm for creating 3d caves that are connected takes a while to explain even though each step isn't too difficult on it's own. The real bummer was having to update all the places where we were using coordinates. I suppose that if we were using a Point class from the beginning then adding a z coordinate to the Point would have required far fewer changes. Or we could have stuck to a list of 2d arrays and just tracked the current one instead of simulating a 3d world all at once. Oh well. Maybe you wont make the same mistake with the next roguelike you make.

download the code

roguelike tutorial 06: hitpoints, combat, and messages

2011-09-06T13:00:00.000-07:00

Currently our hero just gets rid of any foe it bumps into. I think it's time our creatures had a real attack.

public void attack(Creature other){

        int amount = Math.max(0, attackValue() - other.defenseValue());

    

        amount = (int)(Math.random() * amount) + 1;

    

        other.modifyHp(-amount);

    }



    public void modifyHp(int amount) {

        hp += amount;

    

        if (hp < 1)

         world.remove(this);

    }

There's many many different ways to handle how much damage is done but I'll stick with something simple: the damage amount is a random number from 1 to the attackers attack value minus the defenders defense value. It's easy to code, easy to understand, and using only two variables worked fine for Catlevania: Symphony Of The Night. The IDE tells us what else we need to add to our creature class to support this.

private int maxHp;

    public int maxHp() { return maxHp; }



    private int hp;

    public int hp() { return hp; }



    private int attackValue;

    public int attackValue() { return attackValue; }



    private int defenseValue;

    public int defenseValue() { return defenseValue; }

We can rely on constructor injection to set the values.

public Creature(World world, char glyph, Color color, int maxHp, int attack, int defense){

    this.world = world;

    this.glyph = glyph;

    this.color = color;

    this.maxHp = maxHp;

    this.hp = maxHp;

    this.attackValue = attack;

    this.defenseValue = defense;

}

Then update our CreatureFactory.

public Creature newPlayer(){

    Creature player = new Creature(world, '@', AsciiPanel.brightWhite, 100, 20, 5);

    world.addAtEmptyLocation(player);

    new PlayerAi(player);

    return player;

}

public Creature newFungus(){

    Creature fungus = new Creature(world, 'f', AsciiPanel.green, 10, 0, 0);

    world.addAtEmptyLocation(fungus);

    new FungusAi(fungus, this);

    return fungus;

}

As always, play around with the numbers and find something you like.

Now that we have some stats, let's display them on the PlayScreen. Here's what I added to the end of displayOutput:

String stats = String.format(" %3d/%3d hp", player.hp(), player.maxHp());

    terminal.write(stats, 1, 23);

That went well. Adding new functionality was kept to a few small and isolated changes. The earlier decision to move all the creature creation to a factory also reduced the number of places we had to update. Now go fight some fungi!

Since this post is so short let's add another feature: messages. There are so many ways to do this but we're going to think of a way that avoids globals. A global message queue seems like the easiest way to do messaging - and it probably is - but sometimes it's a good idea to stick to a guideline like "don't use global variables" to see if it works in all scenarios and find where the guideline works against you and should be abandoned. I've found that small roguelikes are a perfect place for this kind of experimentation.

Since we're not using a global message queue to hold messages, where should we put the messages? Messages are just extra text for the GUI so maybe they should be part of the PlayScreen? But they're created by things in the world and everything has access to the world so maybe there? That doesn't seem right though. Messages are meant for the player so maybe the PlayerAi should be the receiver of the messages? That kind of make sense because it already gets called by the creature class and creatures are probably going to be the source of most messages. We can pass messages to the ai and any non-player ai can just ignore the messages.

Add a notify method to the creature class. To make it easier for the callers to build messages you can take the string and any parameters the caller passes and format the string for them. A nice convenience.

public void notify(String message, Object ... params){

    ai.onNotify(String.format(message, params));

}

Which means you need the corresponding empty method for the CreatureAi class. We'll make the PlayerAi class add the messages to a list. Other CreatureAi's will just ignore it.

package rltut;



import java.util.List;



public class PlayerAi extends CreatureAi {



    private List<String> messages;



    public PlayerAi(Creature creature, List<String> messages) {

        super(creature);

        this.messages = messages;

    }



    public void onEnter(int x, int y, Tile tile){

        if (tile.isGround()){

         creature.x = x;

         creature.y = y;

        } else if (tile.isDiggable()) {

         creature.dig(x, y);

        }

    }



    public void onNotify(String message){

        messages.add(message);

    }

}

Instead of creating a getter for the message list we rely on constructor injection. That means the list comes from somewhere else that may already have a reference to it. We can create the list in the PlayScreen and pass it to the creature factory which passes it to the new PlayerAi. Since the PlayScreen already has the list, it can easily display any messages that show up and clear the list afterwards.

Here's the update to the CreatureFactory:

public Creature newPlayer(List<String> messages){

    Creature player = new Creature(world, '@', AsciiPanel.brightWhite, 100, 20, 5);

    world.addAtEmptyLocation(player);

    new PlayerAi(player, messages);

    return player;

}

Here's the update to the PlayScreen:

private List<String> messages;



public PlayScreen(){

    screenWidth = 80;

    screenHeight = 21;

    messages = new ArrayList<String>();

    createWorld();

    

    CreatureFactory creatureFactory = new CreatureFactory(world);

    createCreatures(creatureFactory);

}

private void createCreatures(CreatureFactory creatureFactory){

    player = creatureFactory.newPlayer(messages);

    

    for (int i = 0; i < 8; i++){

        creatureFactory.newFungus();

    }

}

Displaying messages can also be done many different ways. If you haven't guessed by now I like to start simple. The simplest way I can think of is to just list them all on the screen at once.

private void displayMessages(AsciiPanel terminal, List<String> messages) {

    int top = screenHeight - messages.size();

    for (int i = 0; i < messages.size(); i++){

        terminal.writeCenter(messages.get(i), top + i);

    }

    messages.clear();

}

Just call that from the displayOutput method. Before clearing the message list, the messages could be copied into a separate list (or list of lists) so the history is preserved.

All we need now is some actual messages. Go ahead and notify the creature wherever it does something interesting or has something happen to it. Here's a sample of what I added to the attack method:

notify("You attack the '%s' for %d damage.", other.glyph, amount);

        other.notify("The '%s' attacks you for %d damage.", glyph, amount);

And now the player can receive notices of what's going on.

What about notifying nearby creatures when something happens? Here's one way to do that:

public void doAction(String message, Object ... params){

        int r = 9;

        for (int ox = -r; ox < r+1; ox++){

         for (int oy = -r; oy < r+1; oy++){

             if (ox*ox + oy*oy > r*r)

                 continue;

         

             Creature other = world.creature(x+ox, y+oy);

         

             if (other == null)

                 continue;

         

             if (other == this)

                 other.notify("You " + message + ".", params);

             else

                 other.notify(String.format("The '%s' %s.", glyph, makeSecondPerson(message)), params);

         }

    }

}

The method makeSecondPerson does a small bit of string manipulation to make it grammatically correct. It assumes the first word is the verb, but that's easy enough to do as long as you don't plan on supporting other languages. It's best to avoid implicit rules like this since the only way to know about it is to already know it or watch it fail when you don't follow the implicit rule. It feels dirty to have gramer rules in with the Creature code so remember to move it somewhere better.

private String makeSecondPerson(String text){

    String[] words = text.split(" ");

    words[0] = words[0] + "s";

    

    StringBuilder builder = new StringBuilder();

    for (String word : words){

        builder.append(" ");

        builder.append(word);

    }

    

    return builder.toString().trim();

}

Then you can call doAction in your creature code and anyone nearby will be notified. Here's some examples:

when the FungusAi spawns a child:

creature.doAction("spawn a child");

while attacking:

doAction("attack the '%s' for %d damage", other.glyph, amount);

or when dying:

public void modifyHp(int amount) {

    hp += amount;

    

    if (hp < 1) {

        doAction("die");

        world.remove(this);

    }

}

Now when playing you can get messages about all these details going on in the world. The more you add the more detailed and deep the world will be.

download the code

roguelike tutorial 05: stationary monsters

2011-09-02T13:00:00.000-07:00

Time for some monsters! I want to keep things simple so our first monster will be a stationary fungus. Sounds too boring? Well then I'll throw in a little something to make things interesting.

If our world's going to have a bunch of creatures then we should start there. Add a list for them to the World class and initialize it in the World constructor.

private List<creature> creatures;

We need a way to get the creature at a specific location.

public Creature creature(int x, int y){
    for (Creature c : creatures){
        if (c.x == x && c.y == y)
            return c;
    }
    return null;
}

And we'll update the addAtEmptyLocation method to make sure we don't add a creature where one already is. This will also be the place to add new creatures to our list.

public void addAtEmptyLocation(Creature creature){
    int x;
    int y;
  
    do {
        x = (int)(Math.random() * width);
        y = (int)(Math.random() * height);
    } 
    while (!tile(x,y).isGround() || creature(x,y) != null);
  
    creature.x = x;
    creature.y = y;
    creatures.add(creature);
}

If we want multiple creatures then we have to change how we display the world. Currently we just display the player. Get rid of that line and let's change the displayTiles method to show any creatures in the section of the world we're interested in.

private void displayTiles(AsciiPanel terminal, int left, int top) {
    for (int x = 0; x < screenWidth; x++){
        for (int y = 0; y < screenHeight; y++){
            int wx = x + left;
            int wy = y + top;

            Creature creature = world.creature(wx, wy);
            if (creature != null)
                terminal.write(creature.glyph(), creature.x - left, creature.y - top, creature.color());
            else
                terminal.write(world.glyph(wx, wy), x, y, world.color(wx, wy));
        }
    }
}

This is actually a very inefficient way to do this. It would be far better to draw all the tiles and then, for each creature, draw it if it is in the viewable region of left to left+screenWidth and top to top+screenHeight. That way we loop through screenWidth * screenHeight tiles + the number of creatures. The way I wrote we loop through screenWidth * screenHeight * the number of creatures. That's much worse. I don't know why I didn't realize this when I first wrote this since I've always drawn the creatures after the tiles. Consider this an example of one way to not do it.

You should be able to run it. It will look the same as before but now we can throw in some more creatures and they'll show up too. Our fungus first needs it's own ai:

package rltut;

public class FungusAi extends CreatureAi {
 
    public FungusAi(Creature creature) {
        super(creature);
    }
}

And add it to our CreatureFactory so we can make them.

public Creature newFungus(){
    Creature fungus = new Creature(world, 'f', AsciiPanel.green);
    world.addAtEmptyLocation(fungus);
    new FungusAi(fungus);
    return fungus;
}

Now modify the PlayScreen to populate the world with fungus.

public PlayScreen(){
    screenWidth = 80;
    screenHeight = 21;
    createWorld();
  
    CreatureFactory creatureFactory = new CreatureFactory(world);
    createCreatures(creatureFactory);
}

private void createCreatures(CreatureFactory creatureFactory){
    player = creatureFactory.newPlayer();
  
    for (int i = 0; i < 8; i++){
        creatureFactory.newFungus();
    }
}

If you run it now you should see some green f's standing about.

We've got some monsters but to way to slay them. Let's work on that now; starting with the Creature class.

public void moveBy(int mx, int my){
    Creature other = world.creature(x+mx, y+my);
  
    if (other == null)
        ai.onEnter(x+mx, y+my, world.tile(x+mx, y+my));
    else
        attack(other);
}

public void attack(Creature other){
    world.remove(other);
}

For now an attack will be an instant kill - just tell the world to get rid of the creature. Later on we can add hitpoints and whatnot.

Here's how the world class can remove a killed creature:

public void remove(Creature other) {
    creatures.remove(other);
}

There you go. Stationary monsters waiting to be slain.

And now time to throw in a little something to make things interesting. What if the fungi were able to reproduce and spread? I really like games where each creature has something special instead of all being the same things with slightly different stats so this could be interesting. We first need to let each creature know when it's time to update itself and whatever else it wants to do for it's turn. First and add a method to the World class that lets each creature know it's time to take a turn.

public void update(){
    for (Creature creature : creatures){
        creature.update();
    }
}

Your IDE is probably letting you know that the Creature class doesn't have an update method. Let's add one that delegates to the ai.

public void update(){   
    ai.onUpdate();  
}

Now your IDE is probably letting you know that the CreatureAi class doesn't have an onUpdate method so go ahead and add an empty one. We want the fungi to spread to a nearby open space every once in a while as part of it's behavior during updating. Here's what I came up with:

package rltut;

public class FungusAi extends CreatureAi {
    private CreatureFactory factory;
    private int spreadcount;
 
    public FungusAi(Creature creature, CreatureFactory factory) {
        super(creature);
        this.factory = factory;
    }

    public void onUpdate(){
        if (spreadcount < 5 && Math.random() < 0.02)
            spread();
    }
 
    private void spread(){
        int x = creature.x + (int)(Math.random() * 11) - 5;
        int y = creature.y + (int)(Math.random() * 11) - 5;
  
        if (!creature.canEnter(x, y))
            return;
  
        Creature child = factory.newFungus();
        child.x = x;
        child.y = y;
        spreadcount++;
    }
}

You can play around with how far it spreads, how often it spreads, and how many times it can spread. Don't forget to modify the newFungus method to pass itself into the FungusAi constructor. The last thing you need to do is tell the world to let everyone take a turn by calling world.update() in the PlayScreen after handling user input. The user's input makes the player move and each creature can move after that. Since we're relying on Java's event handling it would be very cumbersome to make our code pause and wait for user input during the player's onUpdate like with many other roguelikes. Just one tiny detail left. If you run this then you will probably see some exceptions happen because we're adding new creatures to our list while looping through the same list — which you can't do. There are different ways of dealing with this but the easiest I know of is to just make a copy of the list and loop through that instead.

public void update(){
    List<creature> toUpdate = new ArrayList<creature>(creatures);
    for (Creature creature : toUpdate){
        creature.update();
    }
}

download the code
So now you've got some underground caves with a hero and some fungi. You can attack and they can spread. We're a bit closer to being an actual game. Next up, actual combat.

roguelike tutorial 04: the player

2011-08-30T13:00:00.000-07:00

Alright, let's get a hero so we can explore these caves.

We'll need something to represent our player and eventually monsters. They'll all have an x and y coordinate, a glyph, and a color. Since they will be interacting with the world, they should have a reference to that too.

package rltut;



import java.awt.Color;



public class Creature {

    private World world;



    public int x;

    public int y;



    private char glyph;

    public char glyph() { return glyph; }



    private Color color;

    public Color color() { return color; }



    public Creature(World world, char glyph, Color color){

        this.world = world;

        this.glyph = glyph;

        this.color = color;

    }

}

I made the x and y coordinate publicly accessible since they'll be used a lot, we don't need to constrain them or do anything when they change, and I'd rather not have to deal with getters and setters. Getters and setters are almost always a better idea than public fields (especially when using C# properties) but part of software engineering is knowing the rules and part is knowing when to break them. If this turns out to be a bad idea and we wish we used getters and setters instead, then it's not a big deal since most IDE's can automatically create getters and setters and rewrite your code to use those (Encapsulate Field or Generate Getters And Setters in Eclipse).

To implement all the different behaviors of all the different creatures, we could use a bunch of flags representing creature traits, or we could use subclassing, but let's use something that's usually more flexible: delegation. Each creature will have a reference to a CreatureAi and the creatures can let their ai decide what to do. Instead of using what's called constructor injection and passing the CreatureAi in the constructor like we do with the world, glyph, and color, which is usually a good way of doing things, we'll use setter injection.

private CreatureAi ai;

public void setCreatureAi(CreatureAi ai) { this.ai = ai; }

Since the caves we have so far aren't all connected, the player can only walk around in the open area he starts in. We could change how we build the world to make sure that all open cave floors are connected but there's a much easier way to make sure the player can explore everything; we'll let creatures dig through the walls.

public void dig(int wx, int wy) {

    world.dig(wx, wy);

}

And here's our addition to the World class allowing us to dig into cave walls.

public void dig(int x, int y) {

    if (tile(x,y).isDiggable())

        tiles[x][y] = Tile.FLOOR;

}

And the Tile class needs an isDiggable method. This way we don't even have to know what the tile is we can just care about if it can be dug through. If we later add new tiles, no-dig zones, or something else we just need to update this method.

public boolean isDiggable() {

    return this == Tile.WALL;

}

And that's the end of our "stuck in a tiny cave" problem. Any day I solve a tricky problem by adding a few little methods is a good day indeed.

Getting back to our Creature class, creatures will also move around in the world. What happens when they try to enter a new tile is up to the creature's ai.

public void moveBy(int mx, int my){

    ai.onEnter(x+mx, y+my, world.tile(x+mx, y+my));

}

I think were done with the Creature class for now so let's start on the CreatureAi. Remember when we created the setter for the creature's ai? We'll use that to wire up the creature and the creature's ai. The ai also needs to do deal with the creature trying to enter a new tile. We're going to have a specific ai for the player so it doesn't matter what you use here since we are just going to override it. Here's what I came up with:

package rltut;



public class CreatureAi {

    protected Creature creature;



    public CreatureAi(Creature creature){

        this.creature = creature;

        this.creature.setCreatureAi(this);

    }



    public void onEnter(int x, int y, Tile tile) { }

}

Remember when I said we're going to have a specific ai for the player a minute ago? Well here it is:

package rltut;



public class PlayerAi extends CreatureAi {



    public PlayerAi(Creature creature) {

    super(creature);

    }

}

We need to override the onEnter method to dig through walls and walk on ground tiles.

public void onEnter(int x, int y, Tile tile){

    if (tile.isGround()){

        creature.x = x;

        creature.y = y;

    } else if (tile.isDiggable()) {

        creature.dig(x, y);

    }

}

If your world has doors then you can make the player automatically open them by walking into them with code very similar to this.

Instead of checking the tile type directly we just ask if it can be walked on or dug through like with isDiggable. Here's our little addition to the Tile class to support that.

public boolean isGround() {

    return this != WALL && this != BOUNDS;

}

We've got a creature class and classes for creature ai — so far so good. We're going to create a lot of creatures that have the same values, all goblins will have a g glyph etc, and we need to make sure we always wire up the correct ai for each new creature. To centralize and hide all this assembly we'll create a class that's responsible for nothing else: the CreatureFactory. Using a factory means the other code doesn't have to deal with all this assembly each time a new creature is created.

package rltut;



import asciiPanel.AsciiPanel;



public class CreatureFactory {

    private World world;



    public CreatureFactory(World world){

        this.world = world;

    }

}

The only creature we're assembling so far is the player so that's the only method we need to add.

public Creature newPlayer(){

    Creature player = new Creature(world, '@', AsciiPanel.brightWhite);

    world.addAtEmptyLocation(player);

    new PlayerAi(player);

    return player;

}

Since the creature needs to start on some empty space and we don't really care which one, we'll add an addAtEmptyLocation method to the world class and let the world take care of that for us.

public void addAtEmptyLocation(Creature creature){

    int x;

    int y;



    do {

        x = (int)(Math.random() * width);

        y = (int)(Math.random() * height);

    }

    while (!tile(x,y).isGround());



    creature.x = x;

    creature.y = y;

}

All that's left is updating the PlayScreen to display and control our @ rather than scrolling on it's own. Our player is very similar to the current scrolling stuff so it won't be difficult to swap it out.

Remove the centerX and centerY variables and use a variable named player instead. Remove the scrollBy method and replace calls to scrollBy with calls to player.moveBy. (find and replace is your friend for things like this). Also replace references to centerX and centerY with player.x and player.y.

Now that we have a real live hero, we can display that rather than the 'X'.

terminal.write(player.glyph(), player.x - left, player.y - top, player.color());

If you missed any of these steps then the compiler or IDE should let you know. Just remember: error messages are your friend and will help you find what needs to be done.

Now you need to make a CreatureFactory and use it to create the player's creature. This can be done as the last step of the PlayScreen constructor.

CreatureFactory creatureFactory = new CreatureFactory(world);

player = creatureFactory.newPlayer();

Just about everything here was adding new classes or a few little methods. The only code we had to really muck around with was a fairly straightforward swap out of the temporary scrolling stuff. That may have seemed like a lot of work just to replace the X on the screen with an @, but we did a lot more than that and are in a really good position for moving on and adding other monsters.

download the code

roguelike tutorial 03: scrolling through random caves

2011-08-26T13:00:00.001-07:00

Time to work on actual gameplay. Sort of. Well ... not really. A place for gameplay to happen. A world for our heroes, foes, and treasures.

Roguelikes happen somewhere. A somewhere made of floors, walls, rivers, trees, caves, doors, or whatever you can imagine. Since this is a tutorial to show the basics, we'll start with two kinds of environment tiles: cave floors and cave walls. I've found it's often useful to have another kind that represents out of bounds. That way instead of having to always check if something is out of bounds before checking the map about a specific tile, we can just ask and the map and it can tell us it's out of bounds and we can handle that however we want. If you're familiar with the NullObject design pattern then it's very similar; I guess you could call it an OutOfBoundsObject.

Since we're talking about tiles, let's have a Tile class. Each Tile needs to be displayed so we need a glyph to display and a color to display it with. Since we only have a few different tile types, and all tiles of the same type look and behave the same, we can represent the tiles as a java enum.

package rltut;

import java.awt.Color;
import asciiPanel.AsciiPanel;

public enum Tile {
    FLOOR((char)250, AsciiPanel.yellow),
    WALL((char)177, AsciiPanel.yellow),
    BOUNDS('x', AsciiPanel.brightBlack);

    private char glyph;
    public char glyph() { return glyph; }

    private Color color;
    public Color color() { return color; }

    Tile(char glyph, Color color){
        this.glyph = glyph;
        this.color = color;
    }
}

I like using extended ascii characters since AsciiPanel supports code page 437, but if you want to use '#' and '.', or something else entirely, go ahead. This is the place to do that.

Now that we have cave walls and floors, we need a World to hold them.

package rltut;

import java.awt.Color;

public class World {
    private Tile[][] tiles;
    private int width;
    public int width() { return width; }

    private int height;
    public int height() { return height; }

    public World(Tile[][] tiles){
        this.tiles = tiles;
        this.width = tiles.length;
        this.height = tiles[0].length;
    }
}

And now that we have a world made up of tiles we can add some methods to get details about them.

public Tile tile(int x, int y){
        if (x < 0 || x >= width || y < 0 || y >= height)
            return Tile.BOUNDS;
        else
            return tiles[x][y];
    }

public char glyph(int x, int y){
        return tile(x, y).glyph();
    }

public Color color(int x, int y){
        return tile(x, y).color();
    }

By checking for bounds here we don't need to worry about out of bounds errors and check everythime we ask the world about a location.

That's perfect for getting details about our world of tiles but we don't have a way of creating the tiles a World is made of. We could add a bunch of methods to create a World, but I like having the World class only responsible for the running of a world not creating it. Creating a new world is an entirely different and complicated subject that's only relevant at the beginning of a game and should be forgotten about right after we have a world to work with. Something else needs to create, or build, a world. And if we have something else who's only responsibility is building a new world, you could use the Builder pattern and call it a WorldBuilder.

To create a WorldBuilder you need a world size. Then you can call methods, in literate style, to build up a world. Once you've specified how to build the world you want, you call the build method and you get a new World to play with.

package rltut;

public class WorldBuilder {
    private int width;
    private int height;
    private Tile[][] tiles;

    public WorldBuilder(int width, int height) {
        this.width = width;
        this.height = height;
        this.tiles = new Tile[width][height];
    }

    public World build() {
        return new World(tiles);
    }
}

The simplest interesting (i.e. randomized) world I know of is a world of caves. I came up with a basic algorithm to build randomized caves myself, although it's just a simple form of cellular automata and I'm not the first to come up with it. The process is to fill the area with cave floors and walls at random then to smooth everything out by turning areas with mostly neighboring walls into walls and areas with mostly neighboring floors into floors. Repeat the smoothing process a couple times and you have an interesting mix of cave walls and floors.

So the builder should be able to randomize the tiles.

private WorldBuilder randomizeTiles() {
        for (int x = 0; x < width; x++) {
            for (int y = 0; y < height; y++) {
                tiles[x][y] = Math.random() < 0.5 ? Tile.FLOOR : Tile.WALL;
            }
        }
        return this;
    }

And repeatedly smooth them.

private WorldBuilder smooth(int times) {
        Tile[][] tiles2 = new Tile[width][height];
        for (int time = 0; time < times; time++) {

         for (int x = 0; x < width; x++) {
             for (int y = 0; y < height; y++) {
              int floors = 0;
              int rocks = 0;

              for (int ox = -1; ox < 2; ox++) {
                  for (int oy = -1; oy < 2; oy++) {
                   if (x + ox < 0 || x + ox >= width || y + oy < 0
                        || y + oy >= height)
                       continue;

                   if (tiles[x + ox][y + oy] == Tile.FLOOR)
                       floors++;
                   else
                       rocks++;
                  }
              }
              tiles2[x][y] = floors >= rocks ? Tile.FLOOR : Tile.WALL;
             }
         }
         tiles = tiles2;
        }
        return this;
    }

We put the new tile into tiles2 because it's usually a bad idea to update data that you're using as input to next updates. It's hard to explain but if you change the code to not use the tiles2 variable you'll see what I mean.

I don't like all those nested loops. Arrow code like this is usually a bad sign but this is simple enough and only used during world gen so I'll leave it as it is for now. This is also just part of working with multi dimentional arrays in java.

And that's how you can make some caves.

public WorldBuilder makeCaves() {
    return randomizeTiles().smooth(8);
}

So now we can create a World of Tiles to play around in. But in order to play in our new world of cave floors and cave walls, we need to display it. Scrolling is easy to implement so we'll add that now. All this talk of playing reminds me of our PlayScreen class, which makes since because it's responsible for displaying the world we're playing in and reacting to player input.

If we want the PlayScreen class to display a world then we need to make some changes to it. We need to track the world we're looking at, what part we're looking at, and how much of the screen is used for displaying the world. Here's the variables and constructor to add to the PlayScreen:

private World world;
    private int centerX;
    private int centerY;
    private int screenWidth;
    private int screenHeight;

    public PlayScreen(){
        screenWidth = 80;
        screenHeight = 21;
        createWorld();
    }

The createWorld method does exactly that, create's a world. I have a feeling this is going to expand as we make the world more interesting so putting it in a separate method will reduce how tangled it get's with other code and make changes easier later on.

private void createWorld(){
        world = new WorldBuilder(90, 31)
              .makeCaves()
              .build();
    }

We need a method to tell us how far along the X axis we should scroll. This makes sure we never try to scroll too far to the left or right.

public int getScrollX() {
    return Math.max(0, Math.min(centerX - screenWidth / 2, world.width() - screenWidth));
}

And we need a method to tell us how far along the Y axis we should scroll. This makes sure we never try to scroll too far to the top or bottom.

public int getScrollY() {
    return Math.max(0, Math.min(centerY - screenHeight / 2, world.height() - screenHeight));
}

We need a method to display some tiles. This takes a left and top to know which section of the world it should display.

private void displayTiles(AsciiPanel terminal, int left, int top) {
    for (int x = 0; x < screenWidth; x++){
        for (int y = 0; y < screenHeight; y++){
            int wx = x + left;
            int wy = y + top;

            terminal.write(world.glyph(wx, wy), x, y, world.color(wx, wy));
        }
    }
}

Now that we have a world to look at, we need to update the displayOutput method to show the section we're looking at on part of the screen - the rest of the screen is for user stats, messages, etc.

int left = getScrollX();
        int top = getScrollY();
   
        displayTiles(terminal, left, top);

Might as well show where were actually looking while we are here.

terminal.write('X', centerX - left, centerY - top);

We also need a new method to actually scroll. It should make sure we're never trying to scroll out of bounds.

private void scrollBy(int mx, int my){
        centerX = Math.max(0, Math.min(centerX + mx, world.width() - 1));
        centerY = Math.max(0, Math.min(centerY + my, world.height() - 1));
    }

Lastly, we need to add cases the the respondToUserInput code se we scroll based on user input.

case KeyEvent.VK_LEFT:
        case KeyEvent.VK_H: scrollBy(-1, 0); break;
        case KeyEvent.VK_RIGHT:
        case KeyEvent.VK_L: scrollBy( 1, 0); break;
        case KeyEvent.VK_UP:
        case KeyEvent.VK_K: scrollBy( 0,-1); break;
        case KeyEvent.VK_DOWN:
        case KeyEvent.VK_J: scrollBy( 0, 1); break;
        case KeyEvent.VK_Y: scrollBy(-1,-1); break;
        case KeyEvent.VK_U: scrollBy( 1,-1); break;
        case KeyEvent.VK_B: scrollBy(-1, 1); break;
        case KeyEvent.VK_N: scrollBy( 1, 1); break;

And now you have some random caves that you can look around in.

That seems like a fair bit of work. On the other hand, we did create a way to build thousands of worlds (90 tiles by 32 tiles with 2 tiles types = ~~5,760~~ 2^2880 possible worlds) and a way to look around in them so hopefully it's worth it. Not only that, but most of this was from adding new code and not modifying old code; that's always a good sign. You should also try adding new tile types, or tweaking the cave algorithm, changing the world size, importing a hard coded level, or even implementing other world generation algorithms.

download the code

roguelike tutorial 02: input, output, modes, and screens

2011-08-19T13:00:00.000-07:00

Nearly all games follow the same basic main loop:

while the game isn't over:

    show stuff to the user

    get user input

    respond to user input

Roguelikes are no different. But showing stuff to the user, getting user input, and responding to the input doesn't always mean the same thing. Usually we're showing the world and waiting for a player's command but sometimes we're showing a list of spells and waiting for the user to tell us which one to cast or maybe we're showing the player how he died and asking if he wants to play again. Said another way, sometimes we're in "play" mode, sometimes in "select spell" mode, and sometimes "you lost" mode. Each mode has a different way of handling input and output, and I've found that having a different class for each mode with it's own input and output logic is a good way of handling that — much better than having a big mess of if statements and mode-related variables.

Each mode will be represented by a different screen. Each screen displays output on our AsciiPanel and responds to user input; this abstraction can be represented as a simple Screen interface.

package rltut.screens;



import java.awt.event.KeyEvent;

import asciiPanel.AsciiPanel;



public interface Screen {

    public void displayOutput(AsciiPanel terminal);



    public Screen respondToUserInput(KeyEvent key);

}

The displayOutput method takes an AsciiPanel to display itself on and the respondToUserInput takes the KeyEvent and can return the new screen. This way pressing a key can result in looking at a different screen.

The first screen players will see is the StartScreen. This is just a screen that displays some info and sets us in "play" mode when the user hits enter.

package rltut.screens;



import java.awt.event.KeyEvent;

import asciiPanel.AsciiPanel;



public class StartScreen implements Screen {



    public void displayOutput(AsciiPanel terminal) {

        terminal.write("rl tutorial", 1, 1);

        terminal.writeCenter("-- press [enter] to start --", 22);

    }



    public Screen respondToUserInput(KeyEvent key) {

        return key.getKeyCode() == KeyEvent.VK_ENTER ? new PlayScreen() : this;

    }

}

The PlayScreen class will be responsible for showing the dungeon and all it's inhabitants and loot — but since we don't have that yet we'll just tell the player how much fun he's having. It will also respond to user input by moving the player and either setting us in "win" mode if we won the game, or "lose" mode if we lost.

package rltut.screens;



import java.awt.event.KeyEvent;

import asciiPanel.AsciiPanel;



public class PlayScreen implements Screen {



    public void displayOutput(AsciiPanel terminal) {

        terminal.write("You are having fun.", 1, 1);

        terminal.writeCenter("-- press [escape] to lose or [enter] to win --", 22);

    }



    public Screen respondToUserInput(KeyEvent key) {

        switch (key.getKeyCode()){

        case KeyEvent.VK_ESCAPE: return new LoseScreen();

        case KeyEvent.VK_ENTER: return new WinScreen();

        }

    

        return this;

    }

}

Yes, using escape and enter to lose and win is pretty lame, but we know it's temporary and we can swap it out for real stuff later.

The WinScreen will eventually display how awesome our brave hero is and ask if they'd like to play again. But not yet.

package rltut.screens;



import java.awt.event.KeyEvent;

import asciiPanel.AsciiPanel;



public class WinScreen implements Screen {



    public void displayOutput(AsciiPanel terminal) {

        terminal.write("You won.", 1, 1);

        terminal.writeCenter("-- press [enter] to restart --", 22);

    }



    public Screen respondToUserInput(KeyEvent key) {

        return key.getKeyCode() == KeyEvent.VK_ENTER ? new PlayScreen() : this;

    }

}

The LoseScreen will eventually display how lame our foolish hero was and ask if they'd like to play again. But not yet.

package rltut.screens;



import java.awt.event.KeyEvent;

import asciiPanel.AsciiPanel;



public class LoseScreen implements Screen {



    public void displayOutput(AsciiPanel terminal) {

        terminal.write("You lost.", 1, 1);

        terminal.writeCenter("-- press [enter] to restart --", 22);

    }



    public Screen respondToUserInput(KeyEvent key) {

        return key.getKeyCode() == KeyEvent.VK_ENTER ? new PlayScreen() : this;

    }

}

That's it for the screens. Each one is only a dozen or so lines and does only a few simple things. That's a really good sign: small classes with few related responsibilities are good. Very good.

The ApplicationMain class needs to be updated though. It now has to display the current screen when the window repaints and pass user input to the current screen. It's generally best to avoid changing current code but this is only delegating input and output to other things, exactly what ApplicationMain is for. If we were changing it so it handles game logic then I'd be worried, but this is ok.

package rltut;



import javax.swing.JFrame;

import asciiPanel.AsciiPanel;

import java.awt.event.KeyEvent;

import java.awt.event.KeyListener;

import rltut.screens.Screen;

import rltut.screens.StartScreen;



public class ApplicationMain extends JFrame implements KeyListener {

    private static final long serialVersionUID = 1060623638149583738L;



    private AsciiPanel terminal;

    private Screen screen;



    public ApplicationMain(){

        super();

        terminal = new AsciiPanel();

        add(terminal);

        pack();

        screen = new StartScreen();

        addKeyListener(this);

        repaint();

    }



    public void repaint(){

        terminal.clear();

        screen.displayOutput(terminal);

        super.repaint();

    }



    public void keyPressed(KeyEvent e) {

        screen = screen.respondToUserInput(e);

        repaint();

    }



    public void keyReleased(KeyEvent e) { }



    public void keyTyped(KeyEvent e) { }



    public static void main(String[] args) {

        ApplicationMain app = new ApplicationMain();

        app.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);

        app.setVisible(true);

    }

}

Don't forget to update the AppletMain class to handle input and delegate everything to it's current screen.

I'm sure you want to have an @ running around quaffing potions and saying dragons but what we've done so far is very good. Not only are we ready for inventory screens, targeting screens, help screens, and any other screen you can think of, but we've already begin thinking about how user input and output is different than actual gameplay and should be in it's own separate code. Let me repeat, bold, and italicize that: It's good when input, output, and gameplay logic are separate. Once you start mixing them, everything goes downhill. In fact, all we really need to do now is implement the guts of PlayScreen. We'll start that next.

download the code

roguelike tutorial 01: Java, Eclipse, AsciiPanel, application, applet

2011-08-16T13:00:00.000-07:00

This tutorial will be written in Java since I'm familiar with it and it's a decent enough language, has many tools and libraries, a large and helpful community, and runs on Mac, Windows, linux, and web browsers. It's assumed you know at least the basics but I'll explain some of it as I go along. If you have a preferred IDE then go ahead and use that; otherwise, download the latest version of Eclipse since it's powerful and used by may developers, including me. The one other thing this tutorial uses is AsciiPanel (source, jar), a side project I started to help display the old-school ascii graphics so common to roguelikes. Even if you want to support graphics, starting with ascii will let us get started quickly.

So let's get started. Download and start Eclipse (or whatever IDE you're most familiar with) and start up a new project. I'm calling mine "rltut". Download the AsciiPanel jar file and add that to your project.

We'll start with something very simple: just a window with some text on it.

package rltut;



import javax.swing.JFrame;

import asciiPanel.AsciiPanel;



public class ApplicationMain extends JFrame {

    private static final long serialVersionUID = 1060623638149583738L;



    private AsciiPanel terminal;



    public ApplicationMain(){

        super();

        terminal = new AsciiPanel();

        terminal.write("rl tutorial", 1, 1);

        add(terminal);

        pack();

    }



    public static void main(String[] args) {

        ApplicationMain app = new ApplicationMain();

        app.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);

        app.setVisible(true);

    }

}

If you're using Eclipse, your project
should look something like this

A humble beginning, but it means that we have all our tools, libraries, and project settings wired up correctly, which can be one of the most frustrating parts. We'll need a few minor changes but the ApplicationMain class is going to stay simple, it's only responsibility is to create a window and delegate input and output to other things.

The serialVersionUID is suggested by Eclipse and helps to prevent show-stopping failures when serializing different versions of our class. We won't be doing that in this tutorial but it's almost always a good idea to take care of compiler and IDE warning as soon as possible; It will save much trouble down the line.

The ApplicationMain constructor has all the set up code. So far that's just creating an AsciiPanel to display some text and making sure the window is the correct size. The AsciiPanel defaults to 80 by 24 characters but you can specify a different size in it's constructor - go ahead and try it. Play around with the write method while you're at it.

The main method just creates an instance of our window and show's it, making sure that the application exits when the window is closed. Simple as can be.

For extra awesomeness you can make your roguelike run from the users browser as an applet. Just add a file like this to your project:

package rltut;



import java.applet.Applet;

import asciiPanel.AsciiPanel;



public class AppletMain extends Applet {

    private static final long serialVersionUID = 2560255315130084198L;



    private AsciiPanel terminal;



    public AppletMain(){

        super();

        terminal = new AsciiPanel();

        terminal.write("rl tutorial", 1, 1);

        add(terminal);

    }



    public void init(){

        super.init();

        this.setSize(terminal.getWidth() + 20, terminal.getHeight() + 20);

    }



    public void repaint(){

        super.repaint();

        terminal.repaint();

    }

}

It's a good start. You don't have much but anyone can play it since it runs on any modern computer either from the user's browser or downloaded and run from the user's machine.

download the code

roguelike tutorial: the what and why

2011-08-13T17:46:00.000-07:00

Let's make a roguelike!

I've made a few roguelikes — mostly for myself — and I think they're a fun mix of computer science algorithms, code design decisions, and game design decisions. They are also fun to make and a great way to try new programing ideas and new game ideas.

I've created a 20 part series that I'm going to post here where I stumble my way through creating a roguelike that has most of the features any mainstream roguelike has. I consider myself a decent programmer but I'll try some things that may or may not work out and, for the sake of explanation via blog posts, cut some corners and leave out a few details. Because of that, don't take this as an example of the ideal rogulike or ideal code but if you stumble through it with me and add your own ideas, you'll have a roguelike too and, more importantly, may be better armed to make your own roguelike or contribute to someone else's roguelike.

Here's the rundown of what's to come:

Part 01: Java, Eclipse, AsciiPanel, application, applet
Part 02: input, output, modes and screens
Part 03: scrolling through random caves
Part 04: the player
Part 05: stationary monsters
Part 06: hitpoints, combat, and messages
Part 07: z levels and deeper caves
Part 08: vision, line of sight, and field of view
Part 09: wandering monsters
Part 10: items, inventory, inventory screens
Part 11: hunger and food
Part 12: weapons and armor
Part 13: aggressive monsters
Part 14: experience and leveling up
Part 15: help, examine, and look screens
Part 16: throwing and ranged weapons
Part 17: smarter monsters
Part 18: potions and effects
Part 19: mana, spells, and magic books
Part 20: item appearance and identification

Some experience with Java and object oriented programming is expected but I can answer any questions that you may have. Not only am I including the code for each part, but I've got a final version, with a few additional tweaks, running as an applet on my blog.

Nameless roguelike for tutorial

2011-08-13T17:27:00.000-07:00

Here's a little roguelike I made over a few days. It was mostly for my own amusement and to try a few different programming things so it doesn't have anything new or great. I also created a tutorial about how I wrote it. This applet can be downloaded and run from the desktop too.

Standard story: descend the Caves Of Slight Danger, find the lost Teddy Bear, and return to the surface to win. Use what you find to avoid dying. Press [?] for help.

main jar file: https://sites.google.com/site/trystansprojects/rltutfinal.jar
display jar file: https://sites.google.com/site/trystansprojects/asciiPanel.jar

[edit]Some people were having problems with it not displaying correctly. I think I've fixed it but let me know if there are problems.[/edit]

Living with observational tests

2011-08-06T18:50:00.000-07:00

I'd say that at least half of the unit tests I look at end up having a ton of extra work and extra assertions. It's always really frustrated me but I think some developers just find this style of tests to be more helpful. I think some people view tests as a central claim with proof and others view it as a record of observations.

I view unit tests like a math proof or logical argument. I have a claim (also known as an assertion) and I have the simplest proof of that claim I can think of. If my claim is that new bank accounts start with a zero balance then my test will mention the claim in the title and assertion. Maybe something like this:

[Test]

public void NewBankAccountShouldStartWithAZeroBalance()

{

    BankAccount newBankAccount = new BankAccount();

    Assert.AreEqual(0, newBankAccount.Balance, "A new bank account should start with a zero balance.");

}

My recent insight is that others seem to view tests more like a record of observations. Imagine walking through a park and writing what you see and hear along the way. "There's a dog. The dog is barking. There's a tree. There's a guy in a suit. The dog is still barking. There's a jogger." etc. Many of the unit test I see are like this, a walk through some scenario or object lifetime with observations made along the way:

[Test]

public void BankAccountTest()

{

    BankAccount account = new BankAccount();

    Assert.IsTrue(account != null, "The account is not null");

    Assert.IsTrue(account.Balance == 0, "The balance is zero."); 

    

    account.DoSomething("ABC", 123);

    Assert.IsTrue(account.Things.Count == 3, "The account has three things."); 

    Assert.IsTrue(account.Balance == 0, "The balance is zero."); 



    // 60 more lines of stuff somewhat related to bank accounts....

}

My frustrations came from realizing that these tests were written differently than what I prefer but not realizing that it's because there's a completely different way of looking at what a test is. The assertion messages are worded differently, the test is named differently, the assertions are different, the only similarity is that both styles are run from NUnit. These aren't unit tests in the strict meaning, they aren't integration tests, and they aren't really system tests; they're what I think of as observational tests — just a bunch of observations. I couldn't figure out what the point of this kind of test was because there is no point to the test. The assertions seemed irrelevant or superfluous because the assertions aren't used as proof of a central claim, they're just things that the original developer noticed or had on his mind when writing the test. They don't say what something should be or why because they're just observations of how things are — there is no expectation or reasoning behind it — just a bunch of observations.

I'm still not sure what to do with failing assertions on these observational tests. I don't want to delete the entire test because they provide some value to someone (well, actually yes I do want to delete them but I won't). These observational tests often fail but I've never found a bug in the code from these; it's always been a bad test or a valid change in the code that broke the now invalid assertion. There's no point in trying to change the developers who like these tests since not only do they prefer these observational tests but I've already tried and failed. I think that if it doesn't look like an obvious bug then I should just update the assertion or delete it. That's what I've always ended up doing anyway but now I won't waste more than a couple minutes on it since it's not worth the frustration.

A unit test case study

2011-08-05T22:39:00.000-07:00

I've been trying to pay more attention to my process for fixing broken unit tests and I'm trying to improve my writing skills, especially when it comes to descriptive narration, so I'm going to fix a test and write down my thoughts as I go. I'll change the business object names to Widgets and Things, but everything else is exactly what happened as it happened. Here goes.

I ran some of our unit tests and the first one to fail has this error message:

XXX.Test.YYY.Widgets.WidgetsTest:
  Two things should be available.
  Expected: True
  But was:  False

Uh, ok. No indication of which two things were expected or which two things were found. Not a very useful error message. The test name doesn't help me much since the Widgets domain encompasses so much. The Widgets code does use Things though so that part makes sense.

I'm guessing the requirements and code changed so instead of two Things available there are now more. This is what happens with at least 95% of the broken tests I look at. I've gotten all I can from the test name and assertion message so it's time to take a look at the test itself.

public void WidgetsTest()
{
    // 44 lines of code
    Assert.IsTrue(thingList.Count == 2, "Two things should be available.");
    // 17 more lines of code
}

Ugh. I'm not even going to try to wrap my head around this yet. Some people are really good at reading through long methods where state winds in and out of methods but I'm not. I'll start with a small change and use AreEqual instead of IsTrue so the failure message indicates what was expected and what was found.

public void WidgetsTest()
{
    // 44 lines of code
    Assert.AreEqual(2, thingList.Count, "Two things should be available.");
    // 17 more lines of code
}

At least now I can see how many were available. It would be better if I know which two Things were expected so I could assert that only ThingA and ThingB are available. Even better than that would be knowing why so I could add that to the message, something like "ThingA and ThingB should be available if Widget.IsAwesome()". That way someone could see it and say "yup, there's a bug" or "no that's not true anymore". At least that would work better for me but I remind myself that I can't really fault others for writing tests in the style they prefer to work with.

Now I wait nearly five minutes while the tests rebuild then wait about a minute for the test to fail again. New error message:

XXX.Test.YYY.Widgets.WidgetsTest:
  Two things should be available.
  Expected: 2
  But was:  3

That's what I expected. I'm pretty sure no one updated the test when they changed the code. Had it said 0 or 500 or something interesting like that then it might be a bug but I'd say there's now a 99% chance it's just an invalid assertion. There is a reference in the test to an issue number so I look that up....

WTF? This issue has absolutely nothing to do with with Things or Widgets! Maybe it's a typo? Maybe it's a bad April Fools joke? Maybe the test was copied and pasted and this reference was left in? I've noticed that's common; I guess people copy the entire thing and leave in a bunch of irrelevant code and assertions that are no longer needed. I search the tests for the original assertion and see that there's one other test with the same line of code. Not only is almost the entire test is the same as the one that's failing but this one is also older so it's almost certainly a copy-and-paste job. This original test does have a comment with an issue number but when I look that up I find the issue has nothing to do with Widgets or Things either. Maybe I can check source control to see when these tests were made and who made them?

The original developer of both tests is long gone so I can't ask him what this is really about. Another developer who's focus is a different domain has made changes to the failing test eight months ago. He probably won't remember but I'll ask him later if I run into a dead end.

I try looking at our continuous integration logs to see when the test started failing but no luck: our logs only go back a couple months and this has been broken the whole time. *sigh* We've always got broken tests but this one has actually been broken since the beginning of recorded history. Looks like I'll have to dive into the test code and see what it's doing.

The test starts by dropping the database then reloading a backup (I've been here 5 or so years and brought this up before and I still don't know why so many of our tests do this), creates a handful of objects while doing a ton of work with them, reading and writing to the file system and database through it all. It even clears some caches along the way; I've always wondered if so many of other peoples tests do this because of superstition or to make sure we do as much work as possible. There are several comments but they just say the same thing as the code following it with no indication of why any of it is being done. This test seems to be running through some very specific scenario involving Widgets from beginning to end. There's a lot of data and I'm not sure what's relevant and what just happened to be that way. There are 14 scattered assertions, not including the assertions buried within other methods, on seemingly random objects and values. A lot of this work is somewhat related to Widgets but this is the only line related to Things. In fact, only one of the assertions is directly related to Widgets.

Time to recap: I've got a failing assertion in a large test filled with seemingly arbitrary assertions and a lot of work. The test name says nothing about what is expected or why. This failing assertion says nothing about what is expected or why. The issue it refers to is completely unrelated to Things or Widgets and the original developer has moved on to another job. I have no idea when it started failing or why and what it's asserting on doesn't even seem to be relevant to the other work happening in the test. This is all quite normal for our tests. Luckily it's the end of the day so I send an email to the other developer who worked on this eight months ago and leave this until tomorrow.

Here's the email:

Unit test XXX.Test.YYY.Widgets.WidgetsTest has a failing assertion on line 2199. The message is "Two Things should be available.". It looks like this test is from you and Mr Doesn't Work Here Anymore. Are there two specific Things or are any two Things acceptable? Why are those two Things expected and why are three Things a problem?

Hopefully he has some answers.

When I get to work the next day there's no response from the developer I emailed. I move on to some other tasks until I can ask him or someone else.

Eventually another developer is available to help me with this one and we walk through almost the same steps that I did. It turns out that if you look at the beginning of the test a certain way and you look at the issue a certain way, then the test looks like it's related to something implied by part of the issue. The weird part is the test has only one assertion related to that and that assertion is the exact opposite of what the issue says.

After about an hour of rereading it and commenting out chunks of the test to see what happens we figure that the last half of the test is completely unnecessary and we delete it — including the failing assertion. Now the test passes and I can move on to the next test.

git pre-commit hook and hspec

2011-07-29T08:00:00.000-07:00

While working on some hspec stuff, I decided to try out git's pre-commit hook and see if I can make it refuse to commit unless the unit tests pass. It was easy. Here's what I came up with:


#!/bin/sh
echo "Running specs.hs"
exec runhaskell hspec.hs --format=progress --specs specs.hs

Where specs.hs are the file with the specs for the hspec library and the --specs option tells the hspec executable to run it's own specs.

On my Mac I need to make the hook executable by running chmod +x .git/hooks/pre-commit

Some roguelike ideas

2011-07-20T13:14:00.000-07:00

I've always got a few ideas for roguelikes in my mind so I figured I should write some down before I forget.

Allied chat. Instead of having some command list, telling allies what to do would involve typing out a command like you're talking to another player. If NPC's understand a few verbs (attack, go to, defend, follow, help, get, etc.), adjectives (fire, nearby, weak), and nouns (me, the skeleton, a sword, etc.) then you could give simple commands to specific allies, or whoever is in earshot of you.

follow me
Mr Wizzard: defend the temple
get better armor
give me your weapon
priests: help the king
use frost weapons on fire imps

Allies could be made even smarter by having default ones or keeping a history of certain commands and the most recent ones take precedence. So if you tell your allies "defend villagers" then "attack archers", they will attack archers if there are any visible, otherwise they will defend any visible villagers. Or that may be more frustration than it's worth; I don't know.

Random monsters. Each game has several species of monsters that have random attributes for each game. Identifying what their strengths and weaknesses are is part of the fun, just like with potions and scrolls. So in one game Forest Monsters can fly, are immune to poison, and have strong armor; in the next game they leave poisoned corpses, regenerate quickly, and can summon insect swarms. Imagine if none of the random monsters leave corpses or if they're all resistant to magic.

Nomic. A nomic is a type of game that is played by changing the rules of the game. I've seen some very strange things happen so it would need to be limited and simplified for a computer game. Imagine if a roguelike let you vote on new rules from time to time. Maybe you could make using magic a crime, grant money to players for each rat they kill, create a fee for those who want to use large weapons, or even crown yourself emperor. Influencing the other voters could become a game in itself.

ANNOUNCING www.LatinLiteracy.com

2011-06-22T15:21:00.000-07:00

Using the Java Play Framework and hosting on www.playapps.net was so easy that I went ahead and bought my own domain: www.LatinLiteracy.com.

It's just a small start for now, but as I learn more Latin I will continue to add to it. I hope that, in time, it will help me and others learn to read and write Latin.

Play framework

2011-06-17T13:22:00.000-07:00

I took a look at the Play Framework for java web apps and while poking around and trying this and that, I ended up implementing most of my Latin app. I wasn't really trying to, I was just testing how to do certain things and before I knew it, I had a working web app. So far, it's been really easy to work with and really fun.

No longer fit

2011-06-10T11:09:00.000-07:00

I recently added long vowels to my latin project. When spoken, long vowels are held a little longer than regular ones and are indicated by putting a little bar, called a macron, above the vowel: ā, ē, ī, ō, or ū. Java can handle these unicode characters if you specify "-encoding utf8" when compiling but apparently fit can not; so any fit tests that were comparing strings that had macrons were failing. I tried changing my code to convert long vowels into regular vowels when comparing but that was messy and didn't always work right since long and regular vowels are different phonemes. Eventually I decided to do away with fit and switch to JUnit. I lost at least two programming sessions to fiddling with fit, working around fit's limits, and finally reimplementing the tests in JUnit.

So even though I was really looking forward to using fit and I think it could solve many problems I've seen with the *Unit frameworks, for me, at least this time, the costs of using fit vastly outweighed the supposed benefits.

Finally fit

2011-06-08T00:13:00.000-07:00

I'm finally using Fit. I've been interested in it for a long while but I've never had a side project where I really though it would be useful, until lately.

One of my new years resolutions is to learn Latin. And, as usual, while learning that I began thinking about ways to apply it to programming such as an Android app to help someone learn and review Latin. Latin is like everything else invented by people: it's got complicated rules with many exceptions and special cases; perfect fit for TTD and Fit in particular.

I don't have tests around the android specific stuff like moving between actions and handling the gui and persistence, just around conjugating, declining, and translating Latin. Although it's been very helpful it has slowed large scaled refactoring. As I learn more about Latin I have to make major changes to how words and phrases are implemented and then I have to rewrite all the tests so they pass.

It feels helpful but I'll have to wait and see if maintaining all these tests really is worth the extra time and effort.

Does work encourage bad habits?

2011-06-02T20:19:00.000-07:00

"these virtues are formed in man by his doing the actions" -- Aristotle, Nicomachean Ethics

Sometimes I wonder about programming as a job. Does having to add new functionality as fast as possible change how I act when programming for fun? Does having to follow the patterns and decisions others have laid out before me close my mind to better ideas when I'm working on my own projects? At home, I can polish a rough working prototype into something works well and that I'm proud of. At work, I often struggle with what's already there to do even the simplest things and I rarely want others to know I had a hand in the final result.

I'm able to use TTD, BDD, constructor injection, profiling, and all kinds of other techniques on my side projects but for some reason, trying those things at work brings only frustration. They don't work with the frameworks we use, the processes we use, other people don't like them, we don't have time to do it that way, or I'd have to rewrite large sections of code just to get it to work. I work with a lot of smart people and, over the last 6 or 7 years, they've created a product that deals with an amazing amount of externally imposed complexity, but the best advice of the best developers rarely helps. My best attempts almost always fall far short and if statements and hard coding rule the day; I consider it a good day if I'm able to use polymorphism instead of scattered if statements.

One small example: I recently noticed my git commits are too large and include too many changes - just like at work. It's like that at work because of the source control tool and our processes for dealing with it encourage few large commits rather than many small ones. It's very frustrating to try and determine what changed in a file, finding that 60 lines changed, then finding that 50 of those lines were just formatting, and the other 10 lines were for several different reasons. Small and focused commits can prevent this, but if you're not in the habit of doing that, then you forget about it even when you have the chance to. I'm beginning to wonder how much of what I do is due to habits that serve me well enough at work but that I don't want to carry into my personal projects.

Interesting metric

2011-05-27T16:58:00.000-07:00

Recently I did a search through some code for the expression "? true : false". Nearly 20 matches from several different developers. At least it's not breaking anything.

Thank you Michael Feathers

2011-05-20T08:23:00.000-07:00

Michael Feathers's book Working Effectively With Legacy Code is probably the computer book I get the most use out of. There's a lot of books out there that will tell you the principles of good design but this is the very best book for the more tactical stuff, i.e. how to work with the messy code you're given. This book is full of real word scenarios and practical advice and you can tell it's written by a battle-scarred veteran. Because of Working Effectively, I've been able to improve the design of some of the biggest, messiest, and most convoluted static classes I've run into. When I think of which programing book has been the most useful and mind-expanding for me, this one is tied with the Structure and Interpretation of Computer Programs and anyone who programs should read both.