# FreeCraft (fka ALE Clone) Version 1.17

         ___________		     _________		      _____  __
         \_	  _____/______   ____   ____ \_   ___ \____________ _/ ____\/  |_
          |    __) \_  __ \_/ __ \_/ __ \/    \  \/\_  __ \__  \\   __\\   __\
          |     \   |  | \/\  ___/\  ___/\     \____|  | \// __ \|  |   |  |
          \___  /   |__|    \___  >\___  >\______  /|__|  (____  /__|   |__|
    	  \/		    \/	   \/	     \/		   \/
        ______________________                           ______________________
    			  T H E   W A R   B E G I N S
    	   FreeCraft - A free fantasy real time strategy game engine

(C) Copyright 1998-2000 by The FreeCraft Project. Distributed under the "Artistic License"

Contents

## Copyright

Please refer to the LICENSE document provided with this distribution. To proceed beyond this point, is to agree with the licence agreement.

## DISCLAIMER

This software is provided as-is. The author(s) can not be held liable for any damage that might arise from the use of this software.

Use it at your own risk.

## Introduction

Read this for the introduction: readme.html

## Install

Read this how to install FreeCraft: install.html

## Upgrade

If you upgrade from an older beta version to a new one, please always run build.sh. Some graphics or formats may have been changed. Don't forget to backup your modified files.

Read this how to upgrade FreeCraft: install.html

## Changes

Read this for the history of FreeCraft: ChangeLog.html

## Todo and known bugs

This file contains the known bugs and what we plan in the future: todo.html

## Problems

Read this, if you have problems compiling, installing or playing FreeCraft faq.html

## Features

- Health and mana could be shown on the map.
- Better path finder routines.
- Loading of compressed (gzip) puds.
- Configuration language.
- Easy replace of unit graphics and sounds.
- 64 times greater maps.
- Training queues.
- Waypoints.
- Correct fog of war (terrain changes are not shown).
- Nice looking fog of war (alpha-grayscale)
- More resolutions 640x480, 800x600, 1024x768 and 1600x1200.
- Scripting language.
- Support for upto 6 resources.

## Open projects

Following projects are not assigned: (Please ask before start working)

- Write a map editor. (with support of greater maps)
- Write a AI editor.
- Write front end to FreeCraft. (Scenarios, puds, videos...)
- Or extend the guile-gtk support.
- Write a video player. (fli or own format)
- Create own tilesets and unit graphics.
- Create own sounds, voices, videos and campains.
- Create an icon for window-manager.
- Create a jingle for startup and home-page.
- Write better documentation. (correct my english :-)
- Improved network support.
- Write better sound routines. (with mp3 and midi or xmi support)
- Write "build.sh" for demo-version.
- Port to X11 8bpp or 32bpp, fullscreen and DGA support.
- Port to ggi.
- Port to msdos/djgpp.
- Port to beos.
- Write clone of the new game from the same company. (Graphic and sound formats are mostly the same.)
- Multilanguage support
- And any other help is welcome.

If you want to help, please join the FreeCraft mailing list and check if not already somebody is working on your project. Than tell what you want to make.

## Documentation

Look into the original game documentation for playing instructions. Look into the sources for more informations.

### Command line options

freecraft [OPTIONS] [map.pud|map.pud.gz]

- OPTIONS
  You can currently give following command line options. Use "freecraft -h" to get an uptodate information.
  - -c "file.ccl"
    Load freecraft config file "file.ccl" insteed of the default "libarypath/ccl/freecraft.ccl".
  - -d "path"
    Change the freecraft libary path to "path" insteed of the default "./data" or "/usr/share/games/freecraft/default".
  - -f factor
    Adjust the build costs of units for the computer players by factor.
  - -h
    Show command line help.
  - -l
    Enable command log to "command.log"
  - -p players
    Number of network players to connect.
  - -s frames
    The AI sleeps 'frames' before it starts working.
  - -t factor
    Adjust the build time of units for the computer players by factor.
  - -D
    Video depth = pixel pro point.
  - -F
    Fullscreen videomode.
  - -W
    Windowed videomode.
- map.pud
  Load the map "map.pud" insteed of the default "libarypath/default.cm".
- map.pud.gz
  Load the compressed map "map.pud.gz" insteed of the default "libarypath/default.cm".
- map.cm
  Load the freecraft map "map.cm" insteed of the default.

  If you have compile FreeCraft with guile-gtk support you can use this to get a file requester. "freecraft contrib/req.cm"

- map.cm.gz
  Load the compressed freecraft map "map.cm.gz" insteed of the default.
- If no file is given the default map "libarypath/default.cm" will be loaded.

### Keyboard commands

- `cursor-left`
  Scroll map left. With control scroll faster.
- `cursor-right`
  Scroll map right. With control scroll faster.
- `cursor-up`
  Scroll map up. With control scroll faster.
- `cursor-down`
  Scroll map down. With control scroll faster.
- `RETURN`
  Enter command line.
- `TAB`
  Toggle minimap mode, with/without terrain.
- `+`
  Increase game speed.
- `-`
  Decrease game speed.
- `c`
  Center on selected unit.
- `q`
  Quit program.
- `^`
  Unselect all units.
- `1-9,0`
  Select unit group first time, if group already selected center on group.
- `CTRL + 1-9,0`
  Define unit group.
- `SHIFT + 1-9,0`
  FIXME: code not written.
- `ALT + 1-9,0`
  FIXME: code not written.
- `G`
  Toggle mouse grab mode.
- `P` or `pause`
  Toggle pause mode.
- `S`
  Save complete state.
- `F10`
  Enter game menue.

## CCL: FreeCraft Configuration Language

The CCL is scheme. I use libguile as a quick hack or SIOD (The most recent release is available from this web page) .

You can also enter CCL commands at the message prompt. Each line starting with "(" is taken as CCL command.

### Files

- libarypath/ccl/clone.ccl is loaded before any initialisation.
- libarypath/ccl/freecraft.ccl is loaded before any initialisation. Contains general configuration.
- libarypath/ccl/missile.ccl is loaded from freecraft.ccl. Contains missile configuration.
- libarypath/ccl/sound.ccl is loaded from freecraft.ccl. Contains sound configuration.
- libarypath/ccl/tilesets.ccl is loaded from freecraft.ccl. Contains tileset configuration.
- libarypath/ccl/units.ccl is loaded from freecraft.ccl. Contains units configuration.

### Functions

Without any order:

## Map CCL functions/variables

reveal-map
  Reveal the complete map.
set-fog-of-war!
  Enable or disable the fog of war.
fog-of-war
  Enable the fog of war.
no-fog-of-war
  Disable the fog of war.
minimap-terrain
  Enable display of terrain in the minimap window.
no-minimap-terrain
  Disable display of terrain in the minimap window.
original-fog-of-war
  Enable original like fog of war style.
gray-fog-of-war
  Enable gray fog of war style.
fog-of-war-contrast contrast
  Set the gray style fog of war contrast. Contrast could be from 0 to OO. A contrast of 100 didn't change anything.
fog-of-war-brightness brightness
  Set the gray style fog of war brightness. Brightness could be from -100 to 100. A brightness of 0 didn't change anything.
fog-of-war-saturation saturation
  Set the gray style fog of war saturation. Saturation could be from -100 to 200. A saturation of 100 didn't change anything.

## Unsorted CCL functions/variables

- title-screen
  Change the default title screen ("graphics/ui/title.png").

  (title-screen title)

  - title
    The title graphic file.

  #### Example:

  (title-screen "graphics/ui/ale-title.png")

  Change the title to "graphics/ui/ale-title.png".

- show-health-bar
  Show the health as bar on the map.

- show-health-dot
  Show the health as dot on the map.

- show-mana-bar
  Show the mana as bar on the map.

- show-mana-dot
  Show the mana as dot on the map.

- show-full
  Show full health or mana on the map.

- show-no-full
  Show no full health or mana on the map.

- show-sight-range
  Show the sight range of the selected unit on map.

- show-react-range
  Show the react range of the selected unit on map.

- show-attack-range
  Show the attack range of the selected unit on map.

- speed-mine
  Decrease the mining time by this factor.
- speed-gold
  Decrease the time in a gold deposit by this factor.
- speed-chop
  Decrease the time for chopping a tree by this factor.
- speed-wood
  Decrease the time in a wood deposit by this factor.
- speed-haul
  Decrease the time for haul oil by this factor.
- speed-oil
  Decrease the time in an oil deposit by this factor.
- speed-build
  Decrease the time to build a unit by this factor.
- speed-train
  Decrease the time to train a unit by this factor.
- speed-upgrade
  Decrease the time to upgrade a unit by this factor.
- speed-research
  Decrease the time to research by this factor.
- speeds
  Decrease the time off all by this factor.
- tileset
  Defines a tileset.

  (tileset slot-name name file table)

  - slot-name
    The tileset slot name.
  - name
    The tileset name.
  - file
    The tileset graphic file.
  - table
    The conversion table from pud tile number (0 - 0x9DF) into internal tile number.

  #### Example:

  (tileset 'tileset-summer "summer" "summer.png" #( ... ) )

  Define the tileset slot 0 as summer with the graphics in summer.png. #( ... ) is the conversion table of 2528 entries.

- missile-type
  Defines the missile types.

  (missile-type slot name file width height)

  - slot
    The missile slot number.
  - name
    The missile name.
  - file
    The graphic sprites file.
  - width
    The width of a sprite.
  - height
    The height of a sprite.

  #### Example:

  (missile-type MissileLightning "Lightning" "lightning.png" 32 32)

  Define the missile slot 0 as "Lightning".

- define-unit-type
  unittype.html
- print-unit-type-table
  unittype.html
- unit-type
  Get the pointer to the unit type structure.

  (unit-type ident)

  ident
    The unit-type unique identifier.

  #### Example:

  (unit-type "unit-peon")

  Get the unit type structure of the peon. #

- unit-type-array
  Get an array of all currently defined unit type structures.

  (unit-type-array)

- get-unit-type-ident
  Get the unique identfier of the unit type structure.

  (get-unit-type-ident type)

  type
    Unit type pointer

  #### Example:

  (get-unit-type-ident (unit-type "unit-peon"))

  Get the identifier of the unit type peon.

- define-map
  Define the size of a new map.

  (define-map width height)

  - width
    The width of the new map.
  - height
    The height of the new map.

  #### Example:

  (define-map 256 256) Define a new map of the size 256 x 256.

- load-pud
  Load a map in pud format.

  (load-pud name)

  - name
    The file name.

  #### Example:

  (load-pud "data/default.pud.gz") Load "default.pud.gz".

- freecraft-map
  Define a map in freecraft own format.

  (freecraft-map ...)

  FIXME: Must write docu

- key-scroll-speed
  Set the speed of keyboard scrolling.

  (key-scroll-speed speed)

  - speed
    Number frames to wait between scrolls.

  #### Example:

  (key-scroll-speed 1) Sets keyboard scrolling speed to fastest.

- mouse-scroll-speed
  Set the speed of mouse scrolling.

  (mouse-scroll-speed speed)

  - speed
    Number frames to wait between scrolls.

  #### Example:

  (mouse-scroll-speed 10) Sets mouse scrolling speed to pretty slow ( 3 times / second.)

- Sound part
  - sound-thread
    Tells freecraft engine to use a threaded sound server. MUST be used in the sound.ccl file, BEFORE the game fully starts. As no effect during the game.
  - sound-volume
    Set global volume.

    (set-sound-volume volume)

    - volume
      The volume from 0 (min=quiet) to 255 (max).

    #### Example:

    (set-sound-volume 128)

    Set volume to 1/2.

  - sound-off
    Turn sound off. Can be later turned on by sound-on.
  - sound-on
    Turn sound on.
  - sound-for-name
    Return a guile sound id to be used in other functions.

    (sound-for-name name)

    - name
      The name of the sound (a string).

    #### Example:

    (sound-for-name "tree chopping")

    Returns the sound id of the tree chopping sound.

  - set-global-sound-range
    Set the cut off distance.

    (set-global-sound-range distance)

    - distance
      The maximum range of a sound in tiles.

    #### Example:

    (set-global-sound-range 64)

    Set the maximal sound range to 64 tiles. Sound events happening more than 64 tiles away from the viewpoint won't be eared.

  - set-sound-range
    Set the cut off distance for a given sound.

    (set-sound-range sound ratio)

    - sound
      The sound either described by its name (a string) or by its guile sound id.
    - ratio
      This value (between 0 and 255) allows to compute the range of the sound. 255 means an infinite range. Any number strictly below 255 is a coefficient that will be applied to the cut off distance: the cut off distance for this sound is ratio/254*cut off distance.

    #### Example:

    (set-sound-range "tree chopping" 50)

    Set the sound range for "tree chopping" to 50/254 times the cut off distance.

  - define-game-sounds
    Allows to define what sounds are going to be used for some game level events (such as the click sound).

    FIXME: Must write docu

  - display-sounds
    Test function. Dump on stdio all the client side mappings between sound names and sound ids.
  - map-sound
    Defines a new mapping between a sound name (a string) and a sound id.

    FIXME: Must write docu

  - make-sound
    Ask the sound server to register a new sound. Ask the sound client to store the mapping between the obtained sound id and the given sound name.

    FIXME: Must write docu

  - play-sound
    Ask the sound server to play a sound.

    FIXME: Must write docu

## Internal Formats

### Tileset

The tileset graphic is loaded from 'png'-files. Only files with 256 indexed colors are currently supported.

The format of the tileset graphic is:

32x32 pixels of a tile.

16 tiles are stored per row.

The pixels (7,6),(7,14),(7,22),(7,30), (15,6),(15,14),(15,22),(15,30), (23,6),(23,14),(23,22),(23,30) and (31,6),(31,14),(31,22),(31,30) are used for the minimap picture. For a 32x32 map all 16 Pixels are used. For a 128x128 map only the first one.

The colors of the palette reserved for the tileset:
HELPME: I don't know!

The conversion table from pud file to the internal format could be changed with ccl. More tileset informations

### User Interface

More user interface informations

### Sprites

The graphics are loaded from 'png'-files. Only files with 256 indexed colors are currently supported.

The format of an unit sprite is:

FIXME: more to come

### Palette

Look into tileset documentation, what I have found.

### Sounds

The sounds are loaded from 'wav'-files. Files with 8 or 16 bit, mono and 11025hz sample frequence are currently supported.

### Utilities

#### extract

Extract a compressed entry out of the original game data file.

Read the knowledge bases which entry contains what.

##### Usage: extract data-file entry output

- data-file
  Compressed input data file. (normaly maindat.war)
- entry
  Entry number of the data-file.
- output
  Output file for the uncompressed entry.

#### gfx2png

Convert compressed graphic (unit sprites) to png graphic file.

##### Usage: gfx2png palette file.gfx

- palette
  Use palette in png file. "palette" is a raw file containing 768 bytes for 256 colors of r g b.
- file.gfx
  File.gfx contains the graphics of the sprites. The output file is file.png.

#### gfu2png

FIXME: must write docu.

#### img2png

FIXME: must write docu.

#### cur2png

FIXME: must write docu.

#### fnt2png

FIXME: must write docu.

#### tile2png

FIXME: must write docu.

#### aledoc

FIXME: must write docu.

## Arts

Following things are used from other peoples. If not other mentioned, protected by the following license "OpenContent License"

cross.png, health.png, mana.png.
  (c) Copyright 1998-2000 by Johns.
food.png
  Food resource icon (c) Copyright 2000 by the Guardian.
score.png
  Score icon in resource (c) Copyright 2000 by the Guardian.
ore,stone,coal.png
  Orc, Stone and coal icon in resource (c) Copyright 2000 by the Guardian.

## Thanks

Thanks to following people for helping me develop freecraft:

- Ari
- Edgar
- Valery Shchedrin
- Iftikhar Rathore
- Charles K Hardin
- Fabrice Rossi
- DigiCat
- Josh Cogliati
- Patrick Mullen
- Vladi Shabanski
- Cris Daniluk
- Patrice Fortier
- FT Rathore
- Trent Piepho
- Josh Cogliati
- Jon Gabrielson
- Lukas Hejtmanek
- Steinar Hamre
- Ian Farmer
- Sebastian Drews
- Jarek Sobieszek
- Anthony Towns
- Stefan Dirsch
- Al Koskelin
- George J. Carrette
- Guardian
- Michael O'Reilly
- Dan Hensley
- Sean McMillian
- Mike Earl
- Ian Turner
- David Slimp
- Iuri Fiedoruk
- Luke Mauldin
- Natan Adams

And to all I have forgot to write up!
Please drop me an email, if I forgot you.

## Contents

- Copyright
- Disclaimer
- Introduction
- Install
- Upgrade
- Changes
- Todo
- FAQ
- Features
- Open projects
- Documentation
  - Command line options
  - CCL: FreeCraft Configuration language
  - Internal Formats
    - Tileset
    - User interface
    - Sprites
    - Sounds
    - Palette
- Utilites
- Arts
- Thanks
- Contents

All trademarks and copyrights on this page are owned by their respective owners.