freeVikings: User's Manual

Jakub Pavlik

Table of Contents

1. Installation
Painless way: "Binary distribution"
Ruby - get it and install
2. Running freeVikings
Windows "binary" release
"Source" release
3. Game controls
4. Configuration file
5. Troubleshooting
6. Known bugs
Infinite loading

Chapter 1. Installation

Game is written completely in Ruby. Because Ruby is an interpreted programming language, it isn't needed (and most probably even not possible) to compile the code. You just have to install Ruby interpreter and a few libraries. Both the interpreter and all needed libraries are licensed by open source licenses and you can download them all for free.

Painless way: "Binary distribution"

If you downloaded "binary distribution" for Windows (available since release 0.7), you can skip this chapter. Package contains everything you need to play freeVikings.

Ruby - get it and install

Ruby version

freeVikings have been developed on Ruby 1.8.4 and tested on Ruby 1.8.6. Some time ago I successfully tested the game on development version of Ruby branch 1.9, but until compatibility with 1.9 is officially declared, it's much safer to install 1.8 in order to play the game.


Ruby is included in most Linux distributions, so the easiest way for you might be to install it using the package manager. Source archive (if you prefer to compile from source - e.g. your distribution doesn't contain up-to-date ruby package and you don't want to upgrade to a newer distribution) can be downloaded at


Go to and download some of the packages marked as stable. I personally have a good experience with the "One Click Installer" - it is a regular self-extracting EXE installer which includes the interpreter, documentation, interactive shell, ri documentation browser, many useful libraries and Nice Ruby IDE.


Libraries you have to install:

  • RUDL (get from SourceForge)


  • Log4r (included in Ruby One-Click installer as a gem; optional since fV 0.6, get from RAA)


RUDL is one of multiple ports of library SDL to Ruby. (It's sometimes said to be the most buggy one. :), but I like it.)


First check you have all libraries listed below. RUDL can build even missing some of them, but it may cause situation that freeVikings won't work. The good message is, that most Linux distributions include binary packages of these libraries.

  • SDL

  • SDL_gfx

  • SDL_image

  • SDL_mixer

  • SDL_ttf

  • SDL_net

  • smpeg

  • freetype

Some Linux distributions may include RUDL as a binary package, but I don't know any. So most of us have to download from SourceForge: Download latest source package (at the time of writing of this document it was release 0.8).

Unpack downloaded RUDL archive and ener the new directory rudl-0.8

	      $ ruby extconf.rb

This checks for required libraries and creates Makefiles.

	      $ make

As superuser type

	      # make install

(If you needed to know how to compile and use RUDL not having access to superuser account, mail me and I will extend this manual for this case.)


Get latest windows binary package from Usually two Windows binary archives are provided - get the one named Unpack it. Execute script install-on-windows.rb . It will open shell window and ask you two questions: if it should continue installing RUDL (you want to answer 'y') and where you want additional DLLs to be put (if you don't know any better place for them, let the installer put them in your ruby/bin directory - I have them there and it works well)


Since freeVikings 0.6 you don't need this library to run freeVikings, because it is useful mainly for development and freeVikings contain a simple bypass which is used if Log4r isn't found. However, even as a non-developer, you might want this library in order to get better informed about what's happening inside freeVikings - e.g. if the game regularly crashes at startup and you want to send me a bug report.

Ruby One-Click installer contains Log4r as a gem. If you want to play freeVikings with Log4r enabled, start game from the commandline:

	    C:\kuba\freeVikings> ruby -rubygems freevikings.rb

It is possible to install Log4r using gems:

	    $ gem install log4r

The second way is to download Log4r as an archive and install it manually: get it from and follow instructions in file INSTALL.

Redistributed libraries

Since release 0.6 part of library script (exactly one file: lib/script.rb) by Joel VanderWerf is distributed with freeVikings. For more information on this library see

Chapter 2. Running freeVikings

Windows "binary" release

Unpack the release archive and execute batch file freevikings.bat. It will start freeVikings using the interpreter and libraries shipped together with the game (regardless you have Ruby installed on your system or not).

"Source" release

You have installed Ruby and all required libraries. Now you can try to run freeVikings. For the first time it is useful to invoke game from the command line, because if it crashes, you see the error output.

	[~]$ cd freeVikings
	[~/freeVikings]$ ruby freevikings.rb

freeVikings accept many useful commandline options. To learn more about them, execute

      [~/freeVikings]$ ruby freevikings.rb --help

Chapter 3. Game controls

I designed freeVikings with aim of immitating Lost Vikings where the old game was good and making it better where needed. Following this philosophy I am doing my best to copy keyboard controls inside game and add a few mouse controls (currently it is possible to use mouse for switching between vikings, selecting item inside inventory and moving items between vikings). On the other side I implemented exitting and giving up differently, because it took several minutes before I guessed how to do this in Lost Vikings.


  • Kill game immediately: [X] button on the window

  • Restart level: F2

  • Return to menu: Esc

  • Pause: P

Switching between vikings:

  • Switch to next viking: Page Up

  • Switch to previous viking: right Ctrl or Page Down

  • Select any viking: left-click on his portrait

All three vikings:

  • Move left/right: cursor key left/right

  • Switch something on: S or cursor key up

  • Switch something off: F or cursor key down

  • Use item: E or U

Baleog (green guy):

  • Use sword: space

  • Shoot arrow: D

Erik (blue guy):

  • Jump: space

Olaf (yellow guy):

  • Change shield position: space

Maybe the most tricky thing in Lost Vikings was inventory using. In freeVikings this traditional tricky keyboard-commanded system has been preserved, but additional possibility to use mouse instead has been added.

Items are collected as vikings touch them, so you don't to bother with pushing any key to collect them. They are stored in vikings' inventories. Every inventory has four slots and if these are full, viking cannot collect any more items. To make some slots free, viking can either delete some item (which might be useful later!) or give it to any of his friends.

On the image below you can see the bottom of game screen. Active viking is Baleog (his portraid is coloured - the others are black and white). The yellow frame shows which item in the inventory is active.

Press Tab. Game is paused and the yellow frame started blinking. You can use cursor keys to move yellow frame around the inventory. If you press Delete now, the active item is deleted. Press Tab again to unpause and continue playing.

You can select another item in viking's inventory also by clicking on it. Mouse can also be used to delete item: click it and drag it to the trash icon.

The most complicated case: you need to move one of Baleog's items to Erik. Before it is possible, all the exchange participants (Erik and Baleog in this case) must touch each other. Now press Tab (pauses game, switches to 'inventory mode') and then Space (which switches to 'items exchanging mode'). Frame in active viking's inventory is now green and blinking. Inventories of vikings which can't participate in the exchange get darker (see Olaf's). Use cursor keys left/right to move active item between vikings. Than push Space to switch to 'normal inventory mode' again.

You can do the same - move items between vikings - also using a mouse. Click an item and drop it over some other viking's portrait or inventory. It should appear in his inventory. If it returns to the inventory where you picked it, you should ensure that the two vikings touch each other (otherwise they can't give items to each other).

Chapter 4. Configuration file

Since release 0.8 you cancustomise default behavior of freeVikings by creating configuration file in your $HOME directory.

Create directory .freeVikings (trailing dot is important!) and copy freeVikings/config/config.rb there. It shouldn't be hard to modify it, because it contains many helpful comments.

If you from any reason can't place your configuration file in the way described above (e.g. your OS doesn't support folders with dot in name), place it wherever you want and define environment variable FREEVIKINGS_HOME which will contain path to directory with your config.rb .

      $ export FREEVIKINGS_HOME=/home/igneus/my_freevikings_home

Chapter 5. Troubleshooting

While playing with freeVikings, you can encounter several kinds of problems. It is usually useful to start program from console, because code of freeVikings is full of debugging output and logging engine is set up so that it should print all important messages to the standard error output. You should also consider running freeVikings with Log4r (as discussed in Chapter 1, Installation)

If you encounter an error and you can't solve it yourself, you can ask me for support. Before writing an e-mail, you should

  1. try to repeat the error and write where and in which circumstances it occurs

  2. copy content of console (you can send it either as text or as screenshot) - error messages printed there are really valuable for me

  3. pack content of directory freeVikings/log (e.g. as a ZIP archive or as a tarball)

I'll do my best to help you.

Chapter 6. Known bugs

Table of Contents

Infinite loading

Infinite loading

Sometimes loading of a level takes forever. It is caused by the way how progressbar is implemented. To avoid this annoying error (if it occurs more often), disable progressbar in the menu (section Graphics) or in your configuration file.