KQ - the console-style roleplaying game
=======================================

KQ is a open-sourced CRPG, with eight characters, over twenty maps,
countless item, spells and enemies, all accompanied by music and sound
effects.

The majority of KQ was developed by JB, until he abandoned it in
Autumn 2002. Due to the wonders of open source, it was rescued by a
team from the Allegro community (http://www.allegro.cc/), including
Peter, 23yrold3yrold, ReyBrujo, Dudaskank, Konforce and Mr Troy, later to
be joined by Team Terradactyl, Steven Fullmer and MasterGoodbytes.
Thanks also are due to:
Sam Hocevar for several fixes and for being the Debian package maintainer
Edge for porting KQ to BeOS, and (with Caz Jones) fixing the joystick code
on that platform.


Building Instructions
=====================

You will need Allegro 4.0 or above, Lua 5.0 or above, DUMB 0.92 or
above. Most of our work was done with the GCC compiler (also known as
MinGW on Windows, DJGPP on DOS). The code should compile on Microsoft
Visual C, but we haven't any project files for it.

Ubuntu:
--------
apt-get install liballegro4-dev
apt-get install libaldmb1-dev
apt install liblua5.3-dev
apt install lua5.3

On Windows:
----------
fix.bat mingw
make depend
make

On Windows in cygwin environment:
----------
./configure
make

On DOS:
-------
fix.bat djgpp
make depend
make

On Mac OS X:
------------
./configure
make

On Linux:
---------
./configure
make

If you have the CVS version, you'll need to do some preparatory work
on Linux and OSX. Type
autoreconf -i
Then ./configure, make as above.


Cheating and Debugging:
==========
To build KQ with support for cheating and debugging, configure with
this command:
./configure --enable-debug --enable-cheats CFLAGS="-g -O0" OBJCFLAGS="-g -O0"

Setting the CFLAGS and OBJCFLAGS are necessary if you want to debug KQ
in gdb, or a similar debugger. Otherwise, the code will appear to jump
around as you step through it. For more info on cheating, see:
http://kqlives.sourceforge.net/index.php/HowToCheat


==========
Without further ado, over to JB: (some of his comments about directory
structure are now out of date)
---------------
Hello.

Disclaimer:
-----------
I just want to point out that this software comes with no warranty at
all, and none is implied.  I can not be held responsible for anything
that happens as a result of your use of this software... you are 100%
liable for anything you do with it.  These conditions apply regardless
of whether or not you took the time to read this.
----------------------------------------------------------------------

Final word from me ---------------------------------------------------

Well, since I'm done developing this guy I guess I should give some
information as to what I was doing.  All you really need to know is
what all of this crap under the main directory is for. Under the
'kqdev' structure are several directories (assuming you unzipped
the archive properly and preserved the directory structure).

kqdev

--- data ---

This includes the data files... all of the WAVs and PCXs are in
the .dat files.  The other two files suffixed .mon are enemy data
files and they are just space delimited text files and could be
easily read into a spreadsheet program if you wanted.

--- maps ---

This contains the map files, the mapdraw.c source file for the
mapdraw program and the PCXs for the tilesets... these tileset PCXs are
copies of the ones in the 'mpcx.dat' file in the 'data' directory.
These PCX files are important for another reason as well since they use
the KQ palette.  I didn't bother including a palette file of any kind,
because all of the paint programs probably use different formats.

--- music ---

These are the music files used by KQ... a couple of them are unused,
but I was too lazy to bother getting rid of them.

--- other ---

This directory contains a good deal of the game data from 'res.c'
in comma delimited files for easy editing in a spreadsheet program.
If you edit the files, you simply save your changes in comma
delimited format and then just feed them into the perl script to
parse them into a nice format that can be cut and paste into 'res.c'
(which is where all of the source-imbedded game data is kept).
If you don't have perl, your best bet is to just edit the 'res.c'
file.  To parse each .csv file just use the kq2h.pl script in this
directory:

perl kq2h.pl filename.csv > whatever.txt

The cut and paste from this .txt file into res.c.

--- saves ---

This should be empty except for a sgupdate.c file which is the
source for the saved game converter program.

--- scripts ---

This directory contains the .lob object files used by the game and
the .lua files that were compiled into the .lob files. Important
to note is that the .lua files under the scripts directory
contain 'macros' and need to be pre-processed using the progress.h
and itemdefs.h files from the parent directory. I have a crappy
perl script called prep.pl that will do this. To compile a .lua
script into a .lob file, do the following if you have perl:

perl prep.pl < filename.lua > temp.tmp
luac -o filename.lob temp.tmp

I tried piping under DOS, but it wasn't working quite right.  Just
try it yourself if you like.

If you don't have perl, there is a 'pscripts' directory under the
'scripts' directory that contains all of the .lua files, but without
macros in them.  Then you can compile these by just doing this:

luac -o filename.lob filename.lua

If you don't use DOS for doing this, things might be slightly
different for you.

That's about it... just make sure you have the following:

- allegro 4.0 or higher (I assume)
- JGMOD 0.98 or higher (I assume)
- Lua 4.0 or higher (I assume)

And, since it's GPL'd you can do whatever you want the source, but
I really could care less.  You can contact me if there are problems
with the .zip or anything of that nature, but I most likely won't
respond to questions about the game itself or things like that...
you're on your own.

Again, I am sorry that I couldn't finish it, but as strange as it may
sound, it's a good thing for me that I don't feel like doing this
anymore... it means my life has gotten better.

/jb (jdb@mb.sympatico.ca)

----------------------------------------------------------------------

Release version 0.91

What's new - 06/07/2002 ----------------------------------------------

- Fixed up all of miscellaneous stuff which consisted mainly of
tweaks and minor bug fixes.
- Built the saved game converter.
- Removed the need for the game.sav (game.dat) file for saved games.

- This makes the engine complete except for combos and perhaps once
again trying to put entities in for random encounters (as opposed to
being attacked by invisible assailants).  Oh, and I guess I need to
make the joystick stuff configurable through the config menu.

What's new - 05/23/2002 ----------------------------------------------

- Added joystick support.  It's not configurable yet, but it should
work.  The only problem is that I haven't fully tested it yet.  I have
a 6-button gamepad, but Allegro is detecting it as a two button one
and KQ is made to not recognize any sticks with less than 4 buttons :)

What's new - 05/06/2002 ----------------------------------------------

- A scripter... a working one... Lua.  It works really well.  I am
using it similar to the way I was using separate map sources though.
I put all events and such into set functions so that I know what to
call from the actual C program.  It's not so smart, but it works.  I
may use the scripter to do other things like spell and item effects,
but no guarantee.  I will need to write up some documentation for the
scripter in case anybody ever tries to use it.

- Note: Lua rocks!

What's new - 03/11/2002 ----------------------------------------------

- Well, I finally got back to work on the game and fixed a bunch of
stuff.  What did I fix you ask?  Well, I mostly took out stuff that
I had put in.  Between the date below and the this date I added quite
a bit of new stuff.  However, over the last couple of days, I have
removed most of it and finalized everything else.  I had a scripter
(for the second time), but that was removed.  I had battle party
sizes of four and three at certain points, and even had it possible
to have all eight characters in the party at one time (with only
four going to fight at once however).  I had implemented a materia
like system using the name 'sparks'.  I even had removed random
encounters and put in entities that you could fight or avoid as you
saw fit (this didn't work that great anyways).  Why did i remove all
this stuff though?  I had to.  With everything I had done, I found
that I was losing interest in the game.  I even got to a point where
I thought I would forget about it and condemn KQ to the RPG
graveyard.  Now I'm back at it, and I've begun work on the remaining
bits of the actual game itself (as opposed to the engine).  Oh,
actually I did leave a couple of things in.  I'll list the changes
between the last version and this one so far:

- shared inventory.  No more individual inventories and swapping
items back and forth.
- changes to the text boxes and their location.  The boxes are more
or less auto-sized to fit the text and they are moved around to
indicate who is speaking.  There is also a slightly different text
box that is used to indicate that the speaker is 'thinking' and not
actually speaking.  The text box font is different as well.
- page numbers on item and spell lists.  Best of all, the page
numbers match inside combat and outside.  If you put Sleep at the top
of page 3 outside of combat, when you access your spell list inside
of battle, Sleep will be at the top of page 3.
- hero attack animations.  They're pretty minimal, but at least it's
something.
- hp/mp bars (in addition to numerical displays) inside combat.  This
is like FF7.
- removed the 'Cast' menu option.  This option simply gave you a list
of only the spells that the character could cast according to current
hp level and location.  Now, you just double-select a spell in the
'Magic' menu to cast it and the spells that you are able to cast are
highlighted.
- minor graphical changes
- code changes for efficiency or convienence reasons

----------------------------------------------------------------------


Default Game controls ------------------------------------------------


Note: These controls are customizable in 'setup.cfg'... as are
various other options.

arrow keys - use these for moving around and navigating menus.

ALT - This is the confirmation key.  Use this to choose menu options,
talk to people, activate things, etc.

CTRL - This is the cancel key.  This will let you back out of menus or
exit from certain options.

ENTER - This brings up the character menu.

ESC - This brings up the system menu.


Menus ----------------------------------------------------------------


Now,  on with the main screen, or map screen (whatever).  This is the
screen where you see everything happening and where you travel around.

From this screen you can activate a couple of menus.  The first menu
we will call the system menu.  It is merely a small menu in the upper
left corner which allows you to Save or Exit the game.  Please note,
that you normally can't save in towns or dungeons, and so the Save
option might be grayed out.  The system menu also contains a Config
option which let's you change various things... check them out for
yourself as the menu contains descriptions of what each options does.

The other menu that you can activate is the character menu.  This is
the menu that lets you look at your party and status and where you can
use items and magic.

The menu options (and what they do) are as follows:

Items:
-----
This shows you the list of a characters items.  The party's items
are pooled, meaning that there is only one inventory which both
party members share.  By default, when you first bring up the
menu, you are in 'Use' mode.  If you select an item, you will use it.
Only items that are usable outside of combat can be used.  If you
press the cancel button, you will go to the little menu, which lets
you choose 'Use', 'Sort' or 'Drop'... or if you press the cancel
button again you will leave the item menu.  If you choose 'Sort',
the items in inventory will be joined and sorted by type.  Choosing
'Drop' allows you to select items to get rid of... this requires
you to choose how many to drop (if there is more than one of the
item) and to confirm that you really want to drop it.

Magic:
------
This option brings up a list of the spells that you have in your
grimoire.  You can have up to 60 spells.  The spells are organized
into pages... 5 pages of 12 spells each.

If you press ALT, and select a spell, the cursor will turn white.
Now you can move the white cursor to a new location and the spell will
go there instead.  If there is a spell in the new location, the spells
will be swapped.

If you press ALT, and select a spell, and then press ALT again, it
will attempt to cast the spell.  If the spell can not be cast outside
of combat you will be beeped!

Equip:
------
This option leads to the equip screen.  This screen is broken into
three sections; the equipped items section (top), the item inventory
section (bottom left), and the preview section (bottom right).

The equipped items section shows what your character already has on.
The possible slots are Hand1 (weapon), Hand2 (shield or nothing if
weapon is two-handed), Head (helmets and caps), Body (armors, robes,
or suits), Arms (guantlets, bracers, or gloves), and Other (special
items like rings, cloaks, etc).

When you enter the equip menu, you are presented with four choices:

Equip:
You select this and then you can cycle through the equipment slots.  As
you move through the list of equipment slots, the inventory window will
indicate what items of that type you have in inventory.  If you select
an equip slot you will be taken to the inventory window where you can
go through the list of compatible items.  The effects each item will
have on your stats shows up in the preview window as you cycle through
them.  If you have no available items that can be equipped in the
selected slot, you will be beeped.

Optimize:
Just like it says, this will equip your character with the best
equipment possible.  Take note though, that this method is not
fool proof... always check over what has been selected for you.
Weapons are selected based on damage alone.  However, the bonus
damage that you cause due to your stats is not reflected in this
decision.  The various armors (shields, headgear, body armor, and
arm-guards) are selected for defense and magic defense benefits only.
Relics are chosen for their overall effect to all stats...
including resistance.  With the exception of Relics, always keep an
eye on how new equipment affects your Aura/Spirit... this is
especially important for heavy magic-users.

Remove:
This works similar to equip.  You move along the equipment slots and
as you do, the effects of de-equipping the item in that slot are
indicated in the preview window.  Selecting a slot removes the item...
as long as you have room in your inventory.

Empty:
This simply removes all equipment as long as there is room in your
inventory.

Spec:
-----
This shows a list of items which are special.  In essence, these
are items that I did not want to leave in the character's
inventory as they are generally essential to the story.  That way
they can't be dropped or sold.  A description of each item is
listed at the bottom as you scroll through the list.

Stats:
------
Quite simply, this option shows the status screen for a character.
The stats are explained as follows:

Exp: your current experience.
Next: the experience you need to rise to the next level.

Strength: influences hit and damage done with most weapons.
Agility: influences hit, evade and damage done with spears
  and daggers.
Vitality: influences defense and hp increases at level up.
Intellect: influences magic defense and mp increases at level up.
  Also affects aura magic attack strength.
Sagacity: influences magic defense and mp increases at level up.
  Also affects spirit magic attack strength.

Aura: this is your ability with aura based magic (mostly damage and
  negative effect spells).
Spirit: this is your ability with spirit based magic (healing spells,
  positive effect spells, and a couple of damage spells).

Attack: your damage potential... the higher the better.
Hit: the higher this is, the less likely you are to miss.
Defense: the higher this is, the less damage you take from attacks.
Evade: the higher this is, the less likely you are to be hit.
MagDef: the higher this is, the less damage you take from magic.

On the top right are your resistance ratings.  The ratings are as
follows:

- a rating less than 0 means you are weak against that element.  If
you are weak against an element, red bars will appear beside it.
Being weak against an element increases damage taken by the the
indicated amount.  For example, three red bars would mean an attack
from that element would do 130% normal damage.
You can not be weak against the last seven elements because they are
status ailments and do not do damage.

- a rating of 0 to 10 indicates normal resistance and will show up as
green bars beside the element.  A rating of 0 is normal and a rating of
10 indicates full immunity to that element (0 damage).

- a rating above 10 means that you are so strong against that element
that you absorb damage from such attacks.  If this is the case, blue
bars will be shown and indicate how much you absorb.  For example,
four blue bars would indicate that you absorb 40% of the damage
taken.  You can't absorb the last seven elements as they do not
cause damage.

Below the resistance ratings is your list of equipment for quick
referral purposes.

Shop menus:
----------
The menus are pretty straight-forward except for a couple of little
things.

At the bottom of the screen, there are boxes with each party member in
them.  If you highlight a weapon or a piece of armor the difference
between that weapon/armor and anything you are currently using/wearing
will show up as a reference.  You will also see if you already have
the item equipped or are carrying it.
When buying spells, it will tell you if you know that spell and/or
whether you are carrying it.
When buying items, it will tell you if you are carrying any of the
items you are looking at.

The other thing is that when you are buying, if you press right you
can increase the quantity that you want to buy (up to 9).  And then,
by pressing left you can decrease the quantity (down to 1 minimum).

Also note that shops carried limited quantities of items.  These items
generally replenish over time, but some do not.  If you sell items to
a shop that normally carries them, it will add that quantity to it's
inventory (up to the normal max that the shop carries).


Combat ---------------------------------------------------------------


Combat is pretty straight forward.  You have one or two characters and
you will encounter one to five enemies.  Sometimes they will surprise
you and get a free attack and sometimes you will suprise them and get
a free attack.  Most of the time, surprise is not a factor.

The battle works mock real-time.  Each combatant has a speed rating
and a speed bar, but there are still rounds for the purpose of
handling spell durations and such.

The enemies attack normally, use magic, or use special abilities.

Your guys can do the following:

Attack - a normal attack using whatever weapon you have.

Spell - cast a spell.  The spells are presented in pages.  The pages
appear in the same order as outside combat.  Any spell that can't be
cast in combat, or you don't have enough mp for will be greyed out.
A note about targetting spells: some spells can be cast on one target
or all of them (or one ally or both).  Just press up or down to target
all and then up or down again to go back to just one target.
Selecting multiple targets decreases the damage done accordingly.

Item - use an item.  You can use most of the items in combat that you
could use outside of combat, plus a few extras.  Items that can not
be used are greyed out.

Invoke - this option will allow you to use any of your equipped gear
in combat.  Some items have special powers that can only be used this
way and only if you've got them equipped.  Invokable items will be
in white.

Defend - this foregoes your attack so that you may better defend
yourself and reduce damage taken.

Run - this attempts to flee from combat.  Doesn't always work.  The
odds of running are higher if all of the enemies have already attacked.
If you surprise the enemy you can run automatically.  Agility is the
key to running... and a little luck.

'Skill' - each character has a special ability that can be used in
combat only.  The ability might not show up due to certain
circumstances.

Rage: increased attack power for one attack.  If the attack is fatal,
the attacker will continue on to the next opponent.  After the attack
is done, the attacker suffers damage.

Sweep: an attack made against all opponents.  The attack is less strong
than a regular attack.  Can only be used when there is two or more
opponents to attack.

Infuse: the caster can cast a spell on him/herself that imbue's him/her
with elemental properties based on the spell.  This can be done once
per combat and only works with elemental type spells.

Prayer: this skill is used multiple times.  If any of the opponents are
undead, this skill will try to dispel them.  If none of the opponents are
undead, then this skill heals the entire party by a random amount.

Boost: this skill is usable once per combat and allows the caster to cast
a single spell as if his/her aura and spirit were 150% higher than normal.
However, a boosted spell also takes 150% normal mp.

Cover: this ability is similar to Defend, but the Covering hero will block
any attacks made against his/her partner as well.  This is usable throughout
an entire combat.

Steal: this allows the hero using the skill to try and steal an item from an
enemy.  Each enemy has up to two items that can be stolen.  The first item is
a common one and if the steal is successful, there is a 95% chance that the
common item is stolen.  If there is a rare item, there is only a 5% chance for
it to be taken.  The chance to steal is based on the hero's level.  Steal is
re-usable throughout combat.

Sense: this allows a hero to view some information about an enemy.  The
information that can be uncovered is hp, maxhp, mp, maxmp, and elemental
resistances.  This is re-usable throughout combat.


Conclusion ------------------------------------------------------------


That's about it for any explanations.

Just wander around, talk to people, explore things and look for bugs.

If you find a bug, just describe it and send mail to:

jdb@mb.sympatico.ca

Thanks.