Final Frontier Trader 0.70 alpha ReadMe
-------------------

********************
Read this with a grain of salt
********************

Thank you for downloading Final Frontier Trader
You can donate money to this project via the link below:
https://www.paypal.com/xclick/business=tomt64%40users.sf.net&item_name=Final+Frontier+Trader&no_note=1&tax=0&currency_code=USD&lc=US

Our website is at http://fftrader.sourceforge,net/
and our SourceForge project page is at
http://sourceforge.net/projects/fftrader/

[ CONTENTS ]

1) Files you need
2) Optional Files
3) Compiling the source
4) Running the game
5) Deafult Controls
6) Creating Addon Packs
6a) 0.67 Addon Pack Specification
7) Creating Scenarios
7a) Map Specification
7b) Scenario Specification

[ 1) Files you need ]

If you downloaded the win32 binary or the source package, you should have
everything you need.  If you downloaded the source from CVS, however, you
may have some difficulty on non *nix systems.  You will need to compile
each library (or find binaries for your system) of each of the libraries
FFTrader uses.  These libraries are:

SDL >= 1.2.4
SDL_image >= 1.2.2
SDL_mixer >= 1.2.4
SDL_ttf >= 2.0.6
SDL_gfx >= 2.0.8
physfs (with zip support) >= 0.1.9

SDL and its libraries may be found easily through Google
or SDL's website (http://www.libsdl.org).
PhysFS may be found at its website (http://www.icculus.org/physfs/)
and includes what is necessary to compile the libraries.
   
[ 2) Optional Files ]

You can download "Addon Packs" from the project page.  These contain
more files that the engine can use.

In v0.67 you can only use these to fly different ships and load graphics
within scenarios.

It is also possible to create your own scenarios for the game or (later)
download new scenarios.  These scenarios require Addon Packs (FPKs) to
work.

[ 3) Compiling the source ]

If you want to compile the source for 0.67 you will need the libraries
listed in section 1.  You will also need to include the DLLs (for Win32)
in your path somewhere, either in the windows/system directory or in
the game directory.  For *nix systems, these libraries must be in your
path too, but usually *nix takes care of that when you install them.

For Windows, Dev-C++ 4.9.9.0 will work.  There is an included Project
for Dev-C++, but you will need the dependencies compatible with
MingW/Dev-C++.  You can find these on the sourceforge project files page.
All you need to do after you have both is to direct your compiler
to the directories of the libraries and includes (/include, /include/SDL,
/lib)

In MSVC, I have included a project file that works for VC++6 and should
work for any later versions (like .NET) on import.  Make sure you have
the libraries ready for use via MSVC's include and library path.

In *nix, there is a makefile.  Simply type "make" after you are sure you
have the proper libraries.  (sorry, no "./configure"... yet)

Mac OS X users can compile using the makefile and Fink.  Just type
"make osx"

Another caveat: it seems that SDL_image relinked with libpng 1.0.15 on
win32 fixes many-a-crash issue, so use the DLLs I provide in the binary
packages for win32, even if you don't compile the game using these.
These DLLs are provided in the Dev-C++ dependencies package.

[ 4) Running the game ]

You can run the game either from the command line, through a Windows
shortcut, or double clicking on the executable.  On the command line,
you can use the following options:
   "-nosmooth" makes all rotated and zoomed surfaces not smoothed by the
       bilinear filter.  This may speed up zoom transition, game loading,
       and moving from sector to sector on lower end machines.
   "-software" renders everything via software rather than hardware.
       Depending on your system, this may speed things up.
   "-fullscreen" makes the game fullscreen.  Use with "-software" if not
       working properly.
   "-showfps" shows your frames per second during main gameplay
   "-log" logs some of the game's internal progress.  This is mainly for
       debug purposes.
       
Example (Windows):
fftrader -nosmooth -software -fullscreen

Example (Linux):
fft -nosmooth -software -fullscreen

[ 5) Default Controls ]

The game's built in controls are:

Up/Down:         Accelerate/Decelerate the ship
Left/Right:      Turn Left or right
Space:           Come to a full Stop
ESC:             Cancel key
p:               Pause/unpause the game
z/x:             Zoom in/out
Keypad +/-:      Zoom the minimap in/out
Left/right CTRL: Two keys for firing weapons
Left/right ALT:  Two keys for engaging/disengaging warp
/ key:           Previous weapon
Right SHIFT      Next Weapon
d:               Dock (at a space station)

These keys are alterable in Options before you start the game, or
within the game by pressing the Cancel key and clicking "Controls".

Using these keys, you can see more or less of the area around you,
go in reverse, pause, start the game over, go to warp, and switch
weapons.

[ 6) Creating Addon Packs ]

When you download addon packs, just put them in the /fpk subdirectory
within the game directory.

If you want to make your own addon pack, you will need to examine
existing ones.  They are simply zip files renamed to *.fpk.

[ 6a) 0.67 Addon Pack Specification ]

Required files in the root of the zip/fpk file:

main.fs - this file must be in the root of your zip/fpk

---MAIN.FS---

You must put these lines into your main.fs file.

(fft-pack
	(name <name>)
	(version <version>)
	(objects )
)

name is the name of your fpk.  This can be anything.

version allows the game to know what version this fpk is.  The
game will use this information and the name information to determine
if your fpk needs to be upgraded to work with a particular scenario.

objects is a command that holds ship and object information for us in
maps and scenarios

Example main.fs

(fft-pack 
	(name MyGraphics)
	(version 1.00)
	(objects
		(playership 
			(playership 
				(displayname Standard Ship)
				(image gfx/ship/ship.png)
				(shield gfx/ship/shield.png)
				(maxwarp 5.0)
				(maxsafewarp 4.8)
				(dimensions 
					(w 70)
					(l 70)
					(d 20)
				)
				(maxspeed 10)
				(turndelay 15)
				(turndelaywarp 500)
				(mmr 0)
				(mmg 0)
				(mmb 255)
				(slot 
					(id 101)
					(w 10)
					(l 10)
					(d 10)
					(type weapon)
				)
				(slot 
					(id 102)
					(w 10)
					(l 10)
					(d 10)
					(type weapon)
				)
				(slot 
					(id 103)
					(w 10)
					(l 10)
					(d 10)
					(type cargo)
				)
				(shootpoint 
					(x 40)
					(y 1)
				)
			)
		)
	)
)

---COMMANDS---

- objects commands:

(playership )                     This command creates a player ship.

(aiship )                         ***Not yet implemented***
                                  This command creates a ship with
                                  Artificial Intelligence (Primarily for 
                                  use with the tools for scenarios and
                                  maps).

(mapobject )                      ***Not yet implemented***
                                  This command creates a map object for use
                                  in a game map (Primarily for use with 
                                  the tools for scenarios and maps).

(activeobject )                   ***Not yet implemented***
                                  This command creates an active object for
                                  use in a game map (Primarily for use with 
                                  the tools for scenarios and maps).

- ship (player and ai) commands (these go under (playership ) or (aiship ):

(displayname <name>)              Instructs the engine to show <name>
                                  when referencing the ship's name.
                                  Example: displayname Standard Ship

(image <image>)                     Instructs the engine to load the image
                                  <image> when displaying the ship on the
                                  screen.  This image must face directly
                                  upward and the pivot point (for rotation)
                                  must be in the exact center of this image.
                                  The full path to this file within the
                                  zipfile must be indicated within <image>.
                                  Example: image gfx/ship.png

(shield <shieldimage>)            ***This command is optional***
                                  Instructs the engine to create a shield
                                  for the ship which will be blitted on top
                                  of the ship.  The shield image may be
                                  bigger than the ship but its center must
                                  be exactly the same as the pivot point of
                                  the ship image.  The shield image must
                                  also appear be "facing" upward, just as
                                  the ship image is.  The full path to this
                                  file within the zipfile must be indicated
                                  within <shieldimage>.
                                  Example: shield gfx/shield.png

(maxwarp <floating point number>) This is the maximum warp speed a ship can
                                  achieve.  If this number is 10.0 or higher,
                                  it will be reduced to 9.9.  If it is less
                                  than 1.0 it will be made 1.0

(maxsafewarp <floating point number>)  This is the maximum warp a ship can
                                  achieve without overheating.  If it is
                                  higher than the maxwarp command, it will be
                                  reduced to be the same as the maxwarp
                                  command's number

(dimensions                       These are the dimensions of the ship.
  (w <num>)                       Width (w ) is left to right size, Length
  (l <num>)                       (l ) is top to bottom size, and depth (d )
  (d <num>)                       is the remaining dimension of the ship which
)                                 cannot be seen in a 2 dimensional game.
                                  These dimensions are purely for statistics
                                  shown on scanners or when you are starting
                                  the game

(maxspeed <integer>)              This is the maximum speed a ship can go
                                  when not travelling at warp.  If this
                                  number is higher than 20, it will be
                                  reduced to 20

(turndelay <integer>)             This number determines how long it takes
                                  to turn the ship left or right while not
                                  at warp.  The higher the number, the longer
                                  it takes.  This number represents 1/10th of
                                  a second, so a value of 10 would mean the
                                  ship would require 1 second of holding down
                                  the left or right keys to turn 5 degrees
                                  left or right.

(turndelaywarp <integer>)         This number determines how long the ship
                                  takes to turn left or right at warp.  The
                                  same rules apply as above.  If the number
                                  is smaller than turndelay, it will be
                                  increased to be the same as the value of
                                  the turndelay

(mmr <integer Red>)               This is the color of the ship as it appears
(mmg <integer Green>)             on the mini-map.  You may, for example,
(mmb <integer Blue>)              make friendly ships green and enemy ships
                                  red.  These use standard RGB values from 0
                                  to 255.  This is ignored for the ship you
                                  are piloting.

(slot 
  (id <num>)                      This command is used to create slots on
  (w <num>)                       a ship that is used to carry cargo holds,
  (l <num>)                       weapons, or other ship components.
  (d <num>)                       Currently this command only recognizes
  (type <string>)                 type "weapon", and ids 101 and 102.
)
                                  
(shootpoint                       ***This command is optional***
  (x <num>)                       This command tells the engine where to
  (y <num>)                       spawn bullets relative to your ship.
)                                 This value is the same as the pixel
                                  coordinates of your image, facing up,
                                  starting with 0,0 as the top left corner.
                                  If this command is not used, the shoot
                                  point defaults to the center or pivot
                                  point of the ship.
                                  
(overheat <int amount>)           ***This command is optional***
                                  This sets the amount of counts to count
                                  when going beyond your cruise or safe
                                  warp speed before the engine overheats
                                  and the ship is destroyed.  The count
                                  increases once every 2 seconds.  The
                                  higher the count, the less chance of
                                  overheating over long periods.  If this
                                  command is not used, it defaults to 20.
                                  Example: overheat 20

[ 7) Creating Scenarios ]

When you download scenarios, just put them in the /scenario subdirectory
within the game directory.

If you want to make your own scenario, you will need to examine
existing ones.  These are scriptable files.  The specifications are below.

I plan to offer tools to create both maps and scenarios in the near future.

[ 7a) Map Specification ]

Map files have script commands that work like this:

(command value)
(command 
	(command2 value1)
	(command3 value2)
)

All commands must be followed by a space, even if the commands are nested

(-- text)  inidcates a comment.

Map files require the following command, in which all other commands must
be nested:

(fft-map 
....
)

Required commands:

(version 1.00)                  indicates the version number as 1.00.
                                All version numbers must have no more
                                than two decimal places

(information 
	(title Test Flight)     indicates the title of the map is
)                               "Test Flight"

(objects )                      indicates a map with no objects in it

With the objects command, you can add different objects to your map:

(objects 
	(mapobject 
		(name Earth)
		(fpk __Base Pack)
		(fpkversion 0.64)
		(x 870)
		(y 870)
		(image gfx/object/planet.png)
		(mmr 0)
		(mmg 255)
		(mmb 0)
	)
	(-- other objects here)
)

With this set of commands, you create an object named Earth, using
the Base Pack (that comes with FFTrader) version 0.64 or greater.
Its coordinates are (870, 870), and its image is gfx/object/planet.png
within the FPK.  Its color on the minimap is yellow, because of the
rgb values of 0,255,0 specified in mmr, mmg, and mmb.
All of the commands listed under mapobject are required.

(objects 
	(actobject 
		(count 40)
		(name asteroid)
		(fpk __Base Pack)
		(fpkversion 0.64)
		(x 0)
		(y 0)
		(orbit 
			(x 0)
			(y 0)
			(distance 
				(random 
					(val1 7000)
					(val2 7300)
				)
			)
		)
		(image gfx/object/asteroid.png)
		(mmr 204)
		(mmg 153)
		(mmb 102)
		(speed 
			(random 
				(val1 1)
				(val2 5)
			)
		)
	)
	(-- other objects here)
)

With this set of commands, you have added an asteroid object to your map.
If you want an active object to be shot at and destroyed in one hit, you
can name it one of the following names:

asteroid

The count command, an optional command, gives you the option to create
many active objects of the same type or with the same orbit center point.
Notice that this would create 40 asteroids that orbit around point (0,0)
at a radius (distance) of 7000 to 7300 pixels, or 7 to 7.3 sectors.
The x and y commands are required, and if you do  not choose to make the
object orbit, it will be treated as a stationary object.  This is like a
map object, except that it can interact with the player in some way.
The orbit command is also optional, and can set up the orbit center and
distance.  The distance can be a number, such as 7000, or it can be a
random number between two values, as shown above.  val1 must be less
than val2.
fpk, fpkversion, image, mmr, mmg, and mmb are required commands, and
their use is explained above in the mapobject section.
speed is a random command that can have a single number or a random number
between two values.  val1 must be less than val2.  If speed is set while
you have not told the object to orbit.  It will go that speed directly up
forever.

(objects 
	(aiship 
		(name aiship)
		(fpk __Base Pack)
		(fpkversion 0.64)
		(x 900)
		(y 700)
		(image gfx/ship/ship.png)
		(mmr 255)
		(mmg 32)
		(mmb 0)
		(color 
			(r 255)
			(g 0)
			(b 0)
		)
		(maxspeed 8)
		(hullhitmax 8)
		(aiscript SIMPLE)
		(aistate AI_STATE_RUN)
	)

	(-- other objects here)
)
This set of commands creates a ship with artificial intelligence.
The x and y commands are required, and indicate where the ship should be
when the map loads for the first time.
fpk, fpkversion, image, mmr, mmg, and mmb are required commands, and
their use is explained above in the mapobject section.
The maxspeed command tells the AI ship that it can only travel at a
maximum speed of "maxspeed", in this case 8.
The hullhitmax command is the amount of hits you can make on the hull of
the AI ship before it is destroyed.
The aiscript command tells the AI ship what level of intelligence to have.
Here are the scripts you can use:

SIMPLE - The simplest AI there is in the game.  It will randomly decide to
run or attack you if you get too close.  When it runs, it runs at maximum
speed, in the exact direction that would take it away from you the fastest.
When it attacks, it will move slowly while close to you, and fast while far
from you.  If you are more than 2 sectors away from it while it is either
attacking you or running from you, it will stop and wait for you to get
close again before doing anything else.  This ship will not attack you or
run from you if you set it's initial state to AI_STATE_STOP, AI_STATE_LOOK,
or AI_STATE_IGNORE.

The aistate command tells the AI ship what state to be in when the map is
first loaded.  The following states are used in the game:

AI_STATE_STOP - The ship will do nothing
AI_STATE_RUN - The ship will run from you
AI_STATE_ATTACK - The ship will attack you
AI_STATE_LOOK - The ship will stay in one position and turn to face you
AI_STATE_IGNORE - The ship will go about it's own business and ignore you
AI_STATE_WAITLOOK - The ship will wait for you to get close while keeping
its face towards you

(objects 
	(station 
		(name Earth Base 001)
		(fpk __Base Pack)
		(fpkversion 0.67)
		(x 600)
		(y 600)
		(image gfx/object/station1.png)
		(mmr 128)
		(mmg 128)
		(mmb 128)
			(shop 
				(buy 
					(item 
						(type bay)
						(price 400)
						(name Heatseeking Missile Launcher)
						(description Holds up to 20 Heatseeking missiles)
						(baytype weapon)
						(holdweapon heatseeking)
						(holdamount 20)
						(fpk __Base Pack)
						(fpkversion 0.67)
						(dispimage gfx/buy/weaponbay.png)
						(w 10)
						(l 5)
						(d 2)
					)
				)
				(sell 
					(item 
						(type cargo)
						(name Water)
						(fpk __Base Pack)
						(fpkversion 0.67)
						(dispimage gfx/buy/water.png)
						(baseprice 10)
					)
				)
			)
		)
		(repairs 
			(shields 
				(baseprice 10)
				(-- you pay 10 credits for every percent of shielding you want back)
			)
			(hull 
				(baseprice 4)
			)
		)
		(shipyard 
			(ship 
				(name Fighter Ship)
				(fpk __Base Pack)
				(price 5000)
			)
		)
	)
	(-- other objects here)
)
This set of commands creates a space station at coordinates (600,600)
The x and y commands are required, and indicate where the station should
be when the map loads.
fpk, fpkversion, image, mmr, mmg, and mmb are required commands, and
their use is explained above in the mapobject section.

The shop command allows you to buy or sell things, by way of the 
buy and sell subcommands.  fpk and fpkversion work like the station
fpk and fpkversion commands.  shop, and subcommands buy and sell are
optional.

Under each shop, you can determine what can be bought or sold there.
Any items of a type that do not exist yet in code can still be bought,
but you lose money and don't get anything for your effort.

The type command accepts:
  cargo
  bay
  ammo
  
Currently, the sell shop only sells cargo.  Other types will be
ignored.

The price or baseprice commands are used to determine how much you buy
or sell items.  baseprice should only be used with baseimport in the
buy shop, and only for items which you want to have limited stock for.
baseimport determines how much the station stocks of the item at first, 
and how much more they get when they are restocked.
dispimage is the image shown when showing what the item looks like.  It
can be different from related images to the item, and should be 100x100
pixels.
name and description are used to show the Name and Description of the
item being sold.
w, l, and d are commands that must exist if the type of item being sold
is a bay.  Bays are added onto ships with open slots that accept that
type of bay.  baytype and holdweapon are also required commands, but
holdamount (how much the bay can hold) is optional.
Currently, holdweapon accepts the following types:
  heatseeking
and baytype accepts the following types:
  cargo
  weapon
If selling ammo, you will need the amount command, which works like this:
  (amount 5)
That sells 5 ammo at a time.  You will also need the image command,
which is a path to the image of the bullet as you want to see it fired in
the game (a small image).
If selling a bay with baytype cargo, (a cargo bay) you will need the
cargounits command, which works like this:
  (cargounits 100)
That allows 100 units of any cargo to fit in the cargo bay.

The repairs command allows the station to repair your ship.  You can
choose to have the station be able to repair shields or your hull.  The
price per percent of repair is determined by the "baseprice" command
under either "shields" or "hull".  Both "shields" and "hull" are
optional commands.

The shipyard command allows you to buy new ships (with only and engine
and no weapons) from the station in question.  Use this just like you
would the startingships command in a scenario file (described below),
except that you must also add the command price, and a number of
credits.  This is the amount you have to pay for the ship.

(objects 
	(bullet 
		(fpk __Base Pack)
		(fpkversion 0.65)
		(id 101)
		(image gfx/object/bullet.png)
	)
)

The bullet command stores bullet images via ids so that the game does
not need to load the image from the hard drive every time an enemy
ship shoots.  This will probably go away later and be replaced by
putting weapons directly onto AI ships.

[ 7b) Scenario Specification ]

Scenario files have script commands that work like this:

(command value)
(command 
	(command2 value1)
	(command3 value2)
)

All commands must be followed by a space, even if the commands are nested

(-- text)  inidcates a comment.

Scenario files require the following command, in which all other commands
must be nested:

(fft-scn 
....
)

Required commands:

(version 1.00)                  indicates the version number as 1.00.
                                All version numbers must have no more
                                than two decimal places

(information 
	(title Test Flight)     indicates the title of the scenario is
	(description blah blah) "Test Flight", and tells its description.
)

(mapfile test-flight.fft-map)   tells the engine where to find the map
                                file within the scenario directory

(start                          tells the engine where the ship you
	(x 700)                 select at startup will start, and what
	(y 700)                 angle and speed it has
	(angle 0)               x and y are coordinates, which are 1000
	(speed 0)	        for every non zero sector.  That is,
	(credits 100)           sector (0,0) covers an area from -1000 to
        (disablewarp )          1000 for both x and y.  Coordinates (0,0)
)                               are in the center of Sector (0,0).
                                Sector (0,1) covers an area from -1000 to
                                1000 on the x coordinate, and 1000 to 2000
                                on the y coordinate.  Also gives you a
                                certain amount of credits (money) to start
                                the game with.  The "disablewarp" command
                                is optional, and disables warp at the
                                beginning of a scenario.  Warp can be
                                enabled when a victory condition is met.
                                
(startingships                  This command tells the engine which
......                          ships you can pick before starting your
)                               game, and from what FPK.

(victory )                      indicates a scenario with no victory
                                conditions (instant win)

---

You can add ships that can be selected as starting ships like this:

(startingships 
	(ship 
		(name Starter Ship)
		(fpk MyF-Pack)
	)
)

This tells the engine that only the ship named "Starter Ship" within
the FPK you named "My F-Pack" (in main.fs) can be selected when
starting this scenario.  Any ship you put here must have the
"isstartership" command in it's script file.

You can also allow all starter ships from all FPKs to be selectable
by simply making "startingships" empty:

(startingships )

---

You can set up victory conditions like this:

(victory 
	(conditionset 
		(meet 1)
		(actobjects 
			(lessthanorequal 0)
			(whenmet enablewarp)
		)
		(aiships
			(equals 1)
		)
	)
)

This makes it so that when all the active objects are gone from the
map, OR there is only 1 AI ship left, you win.  However, this would
make it impossible to complete objective 2 if you destroyed all the
AI ships before the active objects!

The "meet" command tells the engine how many conditions must be met
in that particular condition set

You can check the following for conditions:

actobjects - the active objects, like asteroids
aiships - the AI ships

You can check to see if any of the above:

equals <number> -             the engine will see if the number of
                              what you are checking is exactly equal
                              to <number>
notequal <number> -           the engine will see if the number of
                              what you are checking is not equal to
                              <number>
lessthan <number> -           the engine will see if the number of
                              what you are checking is less than
                              <number>
greaterthan <number> -        the engine will see if the number of
                              what you are checking is greater than
                              <number>
lessthanorequal <number> -    the engine will see if the number of
                              what you are checking is less than or
                              equal to <number>
greaterthanorequal <number> - the engine will see if the number of
                              what you are checking is greater than
                              or equal to <number>
                              
You can also put the "whenmet" command under the conditions.  This
gives you something when you meet a condition.  The following commands
can be used:

(whenmet enablewarp)          This enables warp when the condition it
                              is under is met

When all victory conditions are met, you win.

You can also optionally setup loss conditions.  The way it works is
exactly the same as victory conditions, except for a few key
differences:

- The structure is exactly the same, with the word "loss" instead of
  "victory"
- When you meet these conditions, you lose the game
- The "whenmet" command is not recognized

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

That's all!
Don't forget to visit us for more!

Our website is at http://fftrader.sourceforge.net/
and our SourceForge project page is at
http://sourceforge.net/projects/fftrader/

-TomT64
