V.2 Requirements

From FreeOrionWiki
Revision as of 16:34, 20 January 2005 by (Talk)

Jump to: navigation, search

other Languages:
German / Deutsch: Vorraussetzungen v0.2

composed by Samuel W. Knowlton, aka “Aquitaine,” Drek, and Nightfish
with contributions from the entire FreeOrion team

November 16, 2003

Section I: Format of This Document

There are three types of statements in this document:

  • Declarative design statements: Features will be implemented in the manner described to the exact specifications; any specifications that are unclear or require further detail will be re-submitted to the design team for consideration. These statements are evident from their use of definite punctuation, action verbs such as ‘will’ or ‘shall be’ and are otherwise identified by their unique quality of demonstrating prior thought.
  • General and/or lazy design statements: Features will be implemented in approximately the manner described as the manner described lacks the requisite amount of detail, e.g. ‘a formula shall be determined for a scale of wogs that operates somewhat like this,’ in which the programmer is left to determine the actual formula. These statements are evident from the use of a suggestive, ‘wouldn’t it be nice if’ tone or the sheer implausibility of the feature indicating that no actual developers were consulted at any point during its inception. The design team acknowledges that any future rewriting or clarification of a general or lazy design statement within the same version shall not be attempted without due bribery of the development team.
  • Forward-looking statements: These statements have no bearing on the actual requirements of the version and as such have a tenuous presence at best in a ‘requirements document,’ but are nevertheless included so as to provide some minimal insight into the steaming quagmire of the design team’s vision. These statements are arbitrarily green.
  • Completed sections: These features are already complete and work as intended. They are red whenever there is certainty that the feature is done.

Section II: Version Roadmap

(Note: this section has been deleted. The information was out of date. Use the wiki link to the Roadmap instead.)

Section III: Software Architecture

A client/server model will be employed, in which all calculation and resolution is handled by a trusted server, and the client is merely an interface and a conduit.

  • There will be both server and client programs.
  • The client will provide the player interface into the game.
  • The server will run the game engine.
  • The client will be able to connect to the server locally or over a TCP/IP network.
  • All decisions regarding allowable player actions and universe information the player is allowed to access will be controlled at the server level.
  • The game setup user interface and loading and saving of games will be handled in the server.
  • There will be a user interface screen in the client for setting up the connection to a server. Any locally hosted servers will be auto-detected by the client, and listed in this screen.
  • This will also obviously impact on the number of players and Multiplayer section (hotseat will probably not be supported, although running multiple clients on the same host will allow the same functionality).

Number of Players / Multiplayer

FreeOrion v0.2 will support an arbitrary number of eight players (to be limited formally as v1.0 approaches and bandwidth requirements are known). Because of the client/server model, full multiplayer support will be written in from the beginning.

Section IV: Universe Generation & Game Start Conditions


  • Number of Stars A slider 10 – 500.
  • Shape of Galaxy Cluster, Spiral 2-arm, Spiral 4-arm, Ring, Cluster Pockets, Horseshoe, Origami Bird. The shape that the stars must conform to when being placed into the galaxy.
  • Age of Galaxy Young, Mature, Ancient. Younger universes tend to have more hot stars, fewer blackholes. Ancient universes tend to have more blackholes and cooler stars.
  • Starlanes A UI element will be provided for the following user selections: frequency of long starlanes (default few); frequency of medium starlanes (default some); frequency of short starlanes (default several); the choices will be none, few, some, average, many, and very many. The UI will not permit the user to select ‘none’ for all types of starlanes. A composite value that is an average of the aggregate values will be displayed as a summary descriptor (e.g. ‘mostly average starlanes,’ ‘all sorts of starlanes,’ ‘a mixed amount of short and long starlanes,’ ‘Nightfish starlanes’)
  • Density of Planets Low (3 planets per system), Average (5 planets per system), High (7 planets per system). The density is an average, the number of planet slots always remains 10.
  • Frequency of Specials Common, Rare, Very Rare, Nonexistent. Effects both planet and system specials.

The player may also choose to quick start a game without selecting galaxy options. A quick started galaxy will have the following parameters: user selects number of stars, either a cluster or spiral galaxy shape, mature age, average starlane length and frequency, average planet density, rare specials.

Star System Generation

Star Color

Each star has a color:

  • Blue The hottest stars.
  • White Hotter than average, a very pale green, almost white.
  • Yellow The most common star in a mature galaxy. Average.
  • Orange Cooler than average, a vibrant orange.
  • Red Large cool stars.
  • Neutron The remains of a star from a supernova explosion. Often the location of rips in time-space.
  • Blackhole The event horizon surrounding a singularity formed from the collapse of a super-massive star. Often the location of wormholes leading to other areas of the map.

A set of bonuses (based on base distribution and the Universe’s age) determine the star color. For each environment type, the applicable bonuses (base and age) are tallied and then added to a random number 1-100. The color with the largest final score is assigned to the star.

Star TypesBlueWhiteYellowOrangeRedNeutronBlackhole
Mature  10  1010
Ancient   10102020

Note: Star colors have no gameplay effect aside from modifying the type of planets and system specials generated in a system.

Planet Slots

Each star system has an array of ten slots in which there might or might not be a planet. Taken together, a star system can have 0-10 planets of the following types/sizes:

  • Planetoid Pluto sized. Barely a planet. Can be colonized.
  • Small Mercury sized. Can be colonized.
  • Medium Earth, Venus, Mars. Can be colonized.
  • Large Earth x 1.5. Can be colonized.
  • Massive Earth x 2. Can be colonized.
  • Asteroid Field A ring of debris around a star. An Asteroid Mining Base can be built here.
  • Gas Giant Jupiter, Saturn, Neptune being examples. A Gas Giant Tap can be built here.

A set of bonuses (the slot number, the user option “Planet Density” and the star’s color) help determine the existence/type of a planet. In each slot, for each possibility, the applicable bonuses (slot, user option, and in some cases star color) are tallied and then added to a bell-curved random number 1-100. The possibility with the largest final score is assigned to the planet slot.

  Planet Slot: No WorldPlanetoidSmallMediumLarge Massive Asteroid Field Gas Giant
User Option Low Density70       
Average Density50       
High Density30       
Star Color Blackhole30  -5-5-510-5
Neutrino 55    20 
Slot Slot 110152010   -80
Slot 251015205  -70
Slot 3 51030105 -60
Slot 4 5103010510-30
Slot 5 51020151025 
Slot 6 55520151030
Slot 7 5551510530
Slot 8 10105105530
Slot 951510555530
Slot 10102010   510

Notes: This slot system is a quick a dirty way of generating a general distance from planet to star. Planets in slot 0 are assumed to be about Mercury’s distance from the star. Planets in slot 2 are Earth’s distance from the star, Slot 4 is a bit farther out than Sol’s asteroid belt. Slot 5 would be Jupiter’s distance from the Sun. Slot 9 would be Pluto’s distance.

Distance has no gameplay effect beyond the generation of planet size/type and determining where the planet appears in the UI. Planets closer to the star are generally smaller.

Planet Environments

If a planet exists in a given slot, then a planetary environment is determined, chosen from the following list:

  • Terran Earth-like. Normally holds an abundance of life.
  • Ocean Covered with liquid water. Life abounds.
  • Swamp Venus seen through the eyes of pulp science fiction writers. Humans would find the atmosphere unbreathable, the flora/fauna hostile and poisonous.
  • Toxic The real life Venus. Sulfuric and harsh on humanity, paradise to certain strange breeds of life.
  • Inferno Hell in Space. Much like Toxic, except hotter with a lot more lava. Carbon based life doesn’t thrive here.
  • Radiated A barren world bombarded with Radiation from a nearby star or in some cases a planet with an independently radioactive surface. Life as we know it doesn’t exist, some wildly different species live here anyway.
  • Barren Luna. A dead world by our standards, space-borne organisms often use these rocks as breeding grounds.
  • Tundra Earth minus much of its water and heat. Staunch life can still thrive here.
  • Desert Earth minus much of its water. Pulp science fiction ideal of Mars and Arrakis (Dune) are examples. Temperatures can vary wildly with the time of day, still within the range of liquid water. Terran life is mildly comfortable here.
  • Gaian Gaia worlds are, despite the name, not exclusively paradise for Terran dwellers. They are sentient planets designed by long-forgotten ancient creators to reshape themselves to the whims of their inhabitants. Exceedingly rare, extremely valuable-- some cultures worship Gaian planets as gods.

A set of bonuses (based on the planet’s Size, Slot, Star Color) help determine the environment type. For each environment type, the applicable bonuses are tallied and then added to a bell curved random number 1-100. The environment type with the largest final score is assigned to the planet.

Planet Size Planetoid     1020  -20
Small     1010  -10
Medium10105    55 
Large    1010    -10
Massive   1010    -20
Slot Slot 1-5-5 5203015-2015-50
Slot 210102015201010-1020-40
Slot 3302510 5   15-40
Slot 42525     510-40
Slot 5101055   5 40
Slot 6510510  510 -40
Slot 7      1010 -40
Slot 8-5-5-5 -5 1510-5-50
Slot 9-10-10-10-5-10-102010-10-60
Slot 10-20-20-20-10-20-20255-20-70
Star Color Blue   10152015 5-5
White  5510510 15 
Yellow302520    520 
Orange 555  1010  
Red   10  2010 -5
Neutron-30-30-10553020 5-10
Blackhole-30-30-10-10-101530 -30-15

Game Start Conditions

Each empire will start the game with one planet of at least large size, with 20 population set to ‘balanced’ and 3 missile bases. The planet will be located in the ‘Terran’ slot on the EP wheel (relative to that races’ EP). Each empire will start the game with 2 scouts and one colony ship.

Start locations shall be reasonably far apart. For a very small galaxy, none of the systems in a list of the 5 nearest systems to an empire's starting system should be the starting system for another empire; however, the development team may determine the best manner of spacing systems in small galaxies. This should increase by one system per size larger the galaxy is (for small, no empire should start in the nearest 6 systems to any other empire).

When a map is generated, if it is not possible to fulfill both the minimum starting distance requirement and the large size start planet requirement, then the map will be discarded and a new one generated.

Section V: Planets, Population, and Production

The Wheel of Environmental Preference

How well a race thrives on a planet is based on the distance between the environmental preference (henceforth “EP”) of the race and the planet’s environment on the Wheel of EP:

     Terran -----Ocean
        |          |
        |        Swamp
      Desert       |
        |        Toxic
        |          |
      Tundra       |
        |        Inferno
        |          |

  • If the planet’s environment = the race’s EP then environmental conditions are Optimal.
  • If the planet’s environment is one away from the race’s EP, then environmental conditions are Adequate.
  • If the planet’s environment is two or more away from the race’s EP, then environmental conditions are Terrible.
  • If the planet’s environment = Gaian then the environmental conditions are Superb, regardless of EP.

Note that for v.2, all races have the environmental preference of “Terran”. In future versions, the wheel will also govern terraforming.

Colony Population

When a planet is first colonized, the population is 1.

The maximum limit of a population on a planet is determined by planet size and environmental conditions, referenced on the following table:

Growth Rate50%80%100%100%

This number is called the “Population Cap”. Each turn, population is adjusted via the following formula: New Population = Current Population * ((Population Cap – Current population) / Population Cap)) * Environmental Growth Rate * Race Specific Growth Rate

Obviously, Population needs to be stored as a Float, but displayed to the user cast as an integer.


Normally, there is no explicit migration between the populations of planets.

Certain events assign the planetary feature (aka planet special) “Doomed” to a world. When a planet is “Doomed” the industrial project “Evacuate Planet” is unlocked. For every point of industry spent on Evacuation, one population point worth of citizens enters the migration queue.

Each turn, every unit of population is assigned to a suitable planet within the confines of the empire. If there are no suitable planets (Bad Environment or the pre-existing population is already filled to capacity), then there’s a 25% chance that the population point is lost. Otherwise, the population point remains in the queue to be assigned next turn.

Population in the queue continues to consume food. If there’s a shortfall, population in the migration queue is lost.

(There may be additional effects to evacuation if we have local stockpiles of resources. To be determined later.)

Planet activities

Planet Focus: On each planet, you can select a Major Focus (aka primary classification). The focuses are Farming, Mining, Industry, Science, and Balanced. You may also select a minor focus. Changing focuses costs an undetermined penalty (very likely a monetary one) – there is no penalty for v0.2. Certain buildings can only be placed on worlds with the correct focus. Whenever a focus is changed, any buildings that required the old focus are destroyed. The list of classifications is open to expansion, for example "Entertainment" or "Government."

Production: Each population unit produces one unit of food, one unit of minerals, one unit of science, and one unit of industry; these numbers are then modified by planetary foci, environment, and resource availability as follows:

Primary ClassesFoodMineralsIndustryResearch
Industry116 1
Secondary ClassesFoodMineralsIndustryResearch
Environmental ModificationFoodMineralsIndustryResearch

Resources: One unit of production requires one unit of minerals; food and science do not require resources (at this time).

Stockpiles and resource allocation: Although the issue of stockpiles has been discussed, it did not make it into the v0.2 specs. For v0.2, all resources not consumed locally are sent to an Empire-wide pool and allocated as needed; anything not consumed immediately is wasted. There are no blockades or any external mechanisms affecting this. Stockpiles will be the first issue discussed for v0.3.

Military Production

Planets may be set to ‘build’ one of the following: - Defense Bases (see below) - Ship Types (see below)

If a build setting is changed midway through production, all production on that item is lost and does not transfer. If additional production is left over after completion of of a ship or defense base, production points roll over into a new item of the same type (but are lost if the setting is changed to an un-like ship or base). It is possible to build more than one of a given item in a single turn if there are enough production points to complete them.

Industry: The industrial mechanism for v0.1 (based on percentage of planet industrialized) should be preserved but will not be used for v0.2 The v0.2 model will be further developed for v0.3 once we have finalized precisely what it is that we will be building with industry!)

Every unit of industry produced by the population of a planet is potentially a ‘Production Point’ (PP); each unit of production requires one available unit of minerals. Industry units will first take available minerals from the planet on which the industry unit is produced; they will then take available units from the empire-wide pool. Planets consume resources in descending order of population, followed by number of units produced; for example, a planet producing five small ships or missile bases will produce one missile base, and will not produce a second until all other planets in the Empire have been able to access the empire resource pool once.

Defense Bases: Each defense base provides a static bonus of 3 defense points. Each defense base requires 200 PP to build.

Ships: There are six classes of starship:

  • Scout 0 attack points, 0 defense points. Moves around galaxy. Costs 75 PP.
  • Colony Ship 0 attack points, 0 defense points. Moves around galaxy, creates colonies. 150 PP.
  • Mark I 2 attack points, 1 defense point. Costs 100 PP.
  • Mark II 5 attack points, 2 defense points. Costs 200 PP.
  • Mark II 10 attack points, 3 defense points. Costs 375 PP.
  • Mark IV 15 attack points, 5 defenses points: Costs 700 PP.

All ships move at the same rate on the galactic map. Fleets will have no range limitation.


Starship Combat: Calculated by the AI. No Tactical combat. Algorithms to be determined by uncouth cretin programmers with the following guidelines:

  • Non-combat ships have a low base chance of retreating if they encounter combat ships and have some place to retreat to.
  • If non-combat ships engage in combat and they have an escort, the non-combat ships will be the last things destroyed; consequently, if Player A wins the battle, he may lose some war ships, but he will not lose scout ships or colony ships.
  • Combat ships cannot retreat.
  • Whenever a fleet enters a system that contains enemy planets, it enters combat with –all- planetary missile bases and enemy fleets.
  • When fleets from more than two empires meet, all combat is resolved simultaneously and each fleet will be considered to be targeting the other equally.
  • When a system is conquered, it produces nothing that turn, and any item in production is discarded.

Ground Combat: No ground combat. If an enemy fleet occupies a star system and has destroyed all of the missile bases on a planet, they control the planet.

Research & Technology

Players begin with Scout, Colony ship, and Mark I. Planets producing research points can discover the following (and in the following order):

  • Defense Base 1000 RP.
  • Mark II 1750 RP.
  • Mark III 3500 RP.
  • Mark IV 7000 RP.

Appendix: Interface & Logistics

Core Engine

Each empire will take its turn simultaneously. All actions taken by each empire are resolved at the end of the turn.

During a turn each empire may change planet build options, set split fleets and set fleet destinations, and colonize planets.

Between turns, the game will do the following: 1. Move all fleets that have a set destination. 2. Combine all fleets at each system into consolidated fleets for each empire. 3. Resolve any combat. 4. Check for empire elimination and game end conditions. 5. Update research totals. 6. Update planet population production totals. 7. Place any newly built ships and missile bases.


The following screens must exist to do the following things:

  • Main Menu Options, New Game, Load Game. Load game brings up a list of saved games, and the dates & times on which they were saved.
  • New Game Screen Select the size and shape of the galaxy. Name your Empire and select a color (looking ahead: flags!)
  • Universe Screen Displays starmap with color-coded star systems. Provides a means to select a star system. Star system view does not require its own screen, but at least requires a sizeable window (discretion of graphics team/UI designers). Provides an interface to move fleets. Fleets have names and remain designated between turns. Enemy fleets in deep space will only be visible to the player if the player controls a planet at the destination system for that fleet.

If a fleet with a colony ship stops in a star system that has un-colonized planets, an interface must allow the player to choose whether to colonize any planet in that system. When a player selects to colonize a planet, this will be reflected immediately (in turn), and the player can access the new colony and change its build selection from that point.

The universe screen will show a visible cue as to the destination of fleets in space.

There shall be at least one screen in which the entire galaxy is visible; this can be through either a separate screen, or the ability to zoom in and out of the galaxy screen. Every effort shall be made to keep the names of discovered star systems visible and readable as the player zooms out, within the boundaries of the interface.

At the beginning of each turn, all ships in any given system will be grouped into a single fleet. When the player clicks on the fleet icon, a popup will display the contents of the fleet, and buttons to either move or split the fleet. If the move option is selected, a line will be shown from the system to any system to any system the player points the mouse at, as well as the movement time needed to arrive there. If the split button is selected, the player is presented an interface to select which ships to move into a second fleet. The fleet popup will then show both fleets, with one being highlighted as selected. The player can click on the other fleet to select it. Whichever fleet is selected, the player will still be presented with the same move and split options. In this manner the player can create an arbitrary number of fleets at a system. This interface shall reflect whether or not a fleet has a destination, and what that destination is.

Once a fleet has entered deep space its destination cannot be changed. New movement orders can only be assigned once it has arrived at its destination. The player will not know any more than the name of a system until some ship from his empire has visited that system. After that, the player will have full access to any information regarding that system – including fleets present there. Enemy fleets in deep space will only be visible to the player if the player controls a planet at the destination system for that fleet.

Planet Screen

When a planet is colonized, it begins with 1 population point. Displays current pop, max pop current production balance, and output of food, minerals, research, industry, and production. Shows projected population for next turn based on current growth rate (does not need to display growth rate). All of this information should be accessible without any additional clicks after getting to the planet screen.

The planet screen will provide an interface through which the player may alter the current build selection. If the build selection is set to ships or bases, it will show the number of turns to completion.


There shall be a popup splash window for each new turn with a nifty graphic of some sort and a numbered turn label. Displays all colony activity at the beginning of every turn. How many RPs were generated (total), the number of planets that worked on industrial infrastructure, an alert in case a planet was told to work on industrial infrastructure but had already maxed out, a notice if a planet finished building a ship. A seperate screen for when technologies are discovered. v0.2 simply requires a pop-up before the sit-rep, but the details of this screen are left to the discretion of the graphics team.

Combat pop-up

For every combat that occurs (regardless of whether or not it involves the player), a window that explains the casualties and the outcome. The graphics team shall develop a simple, animated display for automated combat; a primarily text popup with some sound effects and a display of respective fleet/base strength which then reflects casualties as combat rounds are evaluated. Does not need to be interactive. Looking forward: This will develop along the way so that there is still something interesting to look at and listen to when combat is automatically resolved (for example, the difference between space combat and ground combat in MOO2 should be the difference between controllable space combat and automated space combat in FreeOrion).

Save/load/quit menu

A window or screen must exist that allows the player to save the game, load the game, or exit.

Victory window

The player must somehow be notified when they are the sole survivor.