V.3 Requirements/rewrite

From FreeOrionWiki
Jump to: navigation, search

Please Note

The following is a partially complete attempt to bring a design document up to speed to the current state of development. It is also an attempt to make to document more generally useful by focusing on core game concepts and goals, and de-emphasizing preliminary content ideas which can and will change over time.


Section Zero: Major updates and Cliff's Notes

Version v0.2 was largely a refinement of some core ideas that were presented in v0.1. v0.3 expands upon the economy system with the 'meters' idea and defines the technology/research system. It also introduces the beginnings of our event system with the effects document.

The v0.3 DD was mostly complete in July of 2004 but received several cosmetic changes (like Section Zero) and an overhaul of the effects document in September. We've recently weathered yet another web site hiatus and are now on our third host, but the development community remains active and interest is high.

The designers for v0.30 were:

Lead Designer / El Jefe: Samuel Knowlton (aka Aquitaine)
Designer / Alien-in-residence: Drek
Designer / Verbose: Geoff the Medio

With additional kudos, as always, to the FreeOrion Creative Team in its entirety and the ravenous public. They are listed in the Game Design section.

It is my pleasure to participate in this project with such a talented, professional group of people as we are fortunate to have. I look forward to the day when I can raze your cities and conquer your peoples.

Samuel Knowlton
September 21, 2004

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. An entire section that has been completed will be marked as such. Completed subsections are red.

Section II: Version Roadmap

Follow the wiki link to the Roadmap for the most up-to-date version.

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.3 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


The player may set certain options to tailor the galaxy to his parameters, such as number of stars, shape, frequency of planets, and frequency of starlanes, etc.

Game Start Conditions

Each empire will start the game with one planet of medium size. For now, the planet will be ‘Terran’, the EP of every empire until species are implemented.

Start locations shall be reasonably far apart.

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.


  • "Regular" Stars: Around these stars can be found most of the habitable planets. Each color is more or less likely to have planets of particular types. Thus the player can make an educated guess as he explores which stars will be more likely to hold the type of planets he is looking for.
    • Blue The biggest, hottest stars.
    • White Hotter than average, a very pale green, almost white.
    • Yellow Average.
    • Orange Cooler, smaller than average.
    • Red Cool, small, dim stars.

  • "Odd" Stars: These "stars" are less likely to have many planets, especially habitable ones, but may contain other features of interest.
    • Neutron The remains of a star from a supernova explosion. Often the location of rips in time-space.
    • Black hole 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.

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


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:

  • Terrestrial Planets (in the following sizes)
    • Tiny Pluto sized. Barely a planet. Can be colonized.
    • Small Mercury sized. Can be colonized.
    • Medium Earth, Venus. Can be colonized.
    • Large Earth x 1.5. Can be colonized.
    • Huge 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.

Distance has no gameplay effect beyond the generation of planet size/type and determining where the planet appears in the UI.

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
        |          |
      Barren --- Radiated

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.


  • If the planet’s environment = Gaian then habitability is needs to be made to work somehow, regardless of EP.
  • Good - the planet’s environment = the race’s EP
  • Adequate - the planet’s environment is one away from the race’s EP.
  • Poor - the planet’s environment is two away from the race’s EP.
  • Hostile - the planet’s environment is three away from the race’s EP.
  • Uninhabitable - the planet’s environment is four or more away from the race’s EP.

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


Each planet may have a number of planetary specials. These are generally permanent conditions of the planet and can add bonuses and maluses to various meters.

Some Specials:

  • Homeworld: Since there's "no place like home," this special occurs on each species/empire's initial staring planet. It provides a bonuses to the max value of many of the meters.
  • 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. Gaians have "optimal" habitability for any and every species.

Section V: Colonies, Population, & Production

Meters & Infrastructure

Meters are variables attached to planets, representing the production capabilities and social attributes of each colonized world. Future Note: There may eventually be “meters” associated with ships, ship parts, empires, and perhaps the galaxy itself.

Meters always range from 0-100. For greater granularity, meters can be modified in fractions of a full step. As a side note, the effects of a building or technology on a meter should almost always be expressed as integers (eg. "Superlabs gives +4 to research"), and the value of a meter should be rounded to the nearest integer on the UI.

A meter with a value of 20 is at the "breakeven point". A world with Farming set to 20 can feed its own population. A world with Health at 20 doesn't lose or gain population.

Planet Meters have both a Max value and a Current value. The Current Meter slowly increases until it matches the value of its associated Max Meter.

The Max Meters can be thought of as potential infrastructure; the Current Meters represent this potential realized. Bonuses and penalties from foci, technologies, buildings, planet specials, and racial picks influence the Max Meters. Certain catastrophic events (such as bombings and earthquakes) modify the Current Meter, representing damage to actual infrastructure.

After all Effects have executed, if a Meter falls outside the range of 0-100, the Meter is set to either 0 (if below 0) or 100 (if above 100).


The population of a planet consists entirely of the same species— there are no mixed-species planets. This is to simplify the interface and to make it easier to understand how species-specific bonuses and maluses apply to the planet.

Unlike other meters, when a planet is first colonized, Current Population is set to 1.

The Max Population on a planet is determined by planet size and habitability, referenced on the following table:


Max Population can be further modified via planet specials, buildings, and technologies.

Each turn, population is adjusted via the following formulas:

  • If the Health Meter is above 20: Population Change = Current Population * (((Max Population+1) - Current Population) / (Max Population+1)) * (Health Meter - 20) * (0.01)
  • If the Health Meter is equal to 20: Population Change=0
  • If the Health Meter is below 20: Population Change = Current Population * (Health Meter - 20) * (0.01)

Population Change is added to Current Population. If Current Population is over Max Population, then Current Population is reduced to match Max Population.

If Current Population is reduced to 0, then a "Colony Destruction" event is spawned. This event eliminates the colony, and notifies the player on the siterep.


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

Some mechanism will exist to move population from one planet to another under special circumstances.

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.

Construction Meter

The Construction Meter represents the general infrastructure of a planet. It is used to determine the growth rate of Current Meters.

New colonies begin with a Current Construction of 0. Each Homeworld begins the game with Current Construction equal to 75% of its Max Construction.

By default, Max Construction is 20--it is further modified by the effects of buildings, technologies, racial picks, events, planet specials, etc.

Each turn, Current Construction increments via the following formula:

Construction Change = (Current Construction + 1) * ((Max Construction - Current Construction) / (Max Construction+1)) * (Current Population + 10) * (0.01)

Construction Change is then added to Current Construction.

If Current Construction is greater than Max Construction, Current Construction is reduced to match Max Construction. This test should occur after all Effects have been executed.

Infrastructure Labels

Infrastructure Labels have no gameplay effect; the labels are meant to provide an easy method for players to quickly judge the progress of a colony.

A label is selected for each planet based on Current Construction:

  • 1-9: Rural Colony
  • 10-29: Developing World
  • 30-59: Established World
  • 60-89: Heavily Developed World
  • 90-100: Metroplex

The Resource Meters

Resource meters determine the quantity of resource production. There is one resource meter for each type of resource in the game.

On a new colony, all Current Resources Meters begin at 0.

For each planet, quantity of resource production is determined via the following formula:

Resources Produced = (Current Resource Meter/10) * Current Population

The Max Resource Meters are determined by the planet’s Focus settings. (see Focus for details) They are further modified by Effects from various Actors (including technologies, buildings, events, planet specials, and racial picks).

Each turn, all Current Resource Meters increment via the following formula:

Meter Change = Current Construction / (10 + Current Resource Meter)

Meter Change is then added to the Current Resource Meter.

If a Current Meter is greater than its associated Max Resource Meter, then the Current Meter is reduced to match the Max Meter. This test should occur after all Effects have been executed.


Farming determines the amount of Nutrients a world produces. In addition to Focus and the effects of various Actors, this meter is heavily modified by environment:

  • Terrible Environments reduce Max Farming by 30.
  • Adequate Environments reduce Max Farming by 10.
  • Superb Environments have no effect on the Farming meter.
  • Optimal Environments increase Max Farming by 10.


Mining determines the number of Minerals produced. There will probably be planetary specials that modify the Mineral meter, collectively known as the “Mineral Richness specials.”


Industry determines the Production Points (PP) generated by a world. Each Industry point must be matched with a Mineral point to produce PP, as described in the Production section. In addition to Focus and the effects of various Actors, this meter is modified by planet size:

  • Tiny worlds grant a +10 bonus to Max Industry, due to low gravity.
  • Small worlds grant a +5 bonus to Max Industry.
  • Normal sized worlds give no special modifiers to the Industry meter.
  • Large worlds reduce Max Industry by 5, due to heavy gravity.
  • Huge worlds reduce Max Industry by 10.


Science determines the Research generated by a world. In the future, government picks will probably have a significant influence on this meter. "Scientifically interesting” planet specials might modify this meter.


Trade determines the Money extracted from a world. In the future, government picks will probably have a significant influence on this meter. “Valuable commodity” planet specials might modify this meter.

The Social Meters

Unlike the Resource meters, Social meters don’t have separate Max and Current values. Effects always operate on the Current Social Meter.


Health governs the growth rate of population. The Health Meter is based on the Environment of the planet, and can be modified through the usual set of Actors. The Health meter is also heavily influenced by Nutrient Rating, as described in the Nutrient Distribution section.

A higher habitability rating increases the habitability of a planet.

The Health Meter is used by the Population growth formula. As a note, if the Health Meter is below 20, population growth should be negative.

Suggested Future Social Meters

Happiness: Happiness guards against unrest events. It is not used in v.3.

Security: Security lowers the duration of unrest events, guards against piracy events, and guards against enemy espionage. It is not used in v.3

Planet Focus

The player can assign a Primary and Secondary Focus on every colonized planet, representing which resources the planet is "focused" on producing. The values of the Max Resource Meters are determined by Focus settings. Both Foci can be independently set to one of the five resource meters or the "Balanced" setting.

New colonies begin with both the Primary and Secondary Focus set to Balanced. The Homeworld begins the game with Primary set to Balanced and Secondary to Farming.

Focus Effects on Max Resource Meters

Focus settings have these effects on max meter values:

  • Primary Focus adds + 15 to the selected Max Meter
  • Primary Balanced Focus adds +3 to all Max Resource Meters.
  • Secondary Specialized Focus adds +5 to the selected Max Meter
  • Secondary Balanced Focus adds +1 to all Max Resource Meters.

Some technologies and buildings effectively increase the bonus applied by Primary Focus. See Effects for details.

Nutrient Distribution

Note: The nutrient distribution mechanism never got a public review. It may not need one, but this section may be revisited if everyone hates it.

Each unit of population requires Nutrients in order to survive. One point of Nutrients is required for basic survival; two points allow normal health; four points grant good health.

Nutrient Distribution must occur after resource generation, but before population growth is checked.

Each planet has a Nutrient Rating similair to in function to the Enviroment Rating. The Nutrient Rating is determined by dividing Local Nutrients with Population:

  • If Nutrient Rating is 4 or above, the planet is "Well-fed." Health and Happiness increase by 10.
  • If Nutrient Rating is 2 or above (but less than 4), the planet is "Adequately fed". Health and Happiness are unchanged.
  • If Nutrient Rating is 1 or above (but less than 2), the planet is "Poorly fed." Health and Happiness are reduced by 10.
  • If Nutrient Rating is less than 1, then the planet is "Starving." Health and Happiness are reduced by 50. In addition, Health is capped at 19.

During the resource generation phase of a turn, planets with more Nutrients than twice their Current Population export the excess Nutrients to the global stockpile.

During the Nutrient Distribution phase, planets that are "Starving" can import Nutrients from this stockpile to make up for shortfalls. In the first pass, planets import just enough food to reach the "Poorly fed" rating. If, after this first pass there are still Nutrients remaining in the global stockpile, then a second pass is run. During this second pass, planets import just enough food to reach the "Adequate" rating. A third pass is then run, with planets importing just enough food to reach the "Well-fed" rating.

Planets import food in order of colony age. The oldest worlds get first dibs.

Future note: Planets that are "blockcaded" cannot export or import resources.

Section VI: Empire Production

The production philosophy of FreeOrion can be summed up as follows:

  • Building things is only one aspect of the game; this is FreeOrion and not SimGalaxy, so the player should only step in to build something 'special.'
  • There are buildings that are not special but still affect things; these buildings are abstracted into Infrastructure (see above).
  • The building system should prioritize building these 'things that matter' (special buildings, wonders, and ships).

There are four types of buildings:

  • Common buildings: Although they are specific buildings, the player does not choose to build them; they are abstracted into infrastructure and use the Construction meter, rather than production points.
  • Special buildings: These are buildings local to a specific planet, built on it. They must be intentionally built, not automatically done like common buildings. These buildings are built with production points. They may have an effect that over the entire system or over all systems within a certain range.
  • Wonders: Same as special buildings, except each each Empire may only have one of them.
  • Galactic Wonders: Same as wonders, except each galaxy may only have one of them.

Each special building and wonder has a maintenance cost in credits.

The number of special buildings or wonders that can be built via building slots may be limited depending on balance issues pertaining to special buildings or wonders.

Production is managed via a global queue similar to the research queue. Build queue items require a fixed number of PP and turns, although one or both of those values may be affected by racial traits or technology. The player may have multiple build projects going on at the same time. Production points are pooled from all worlds, similar to research points. Whenever a new project is initiated, a location for the item to be built is selected. Buildings may have pre-requisites, including:

  • Primary focus set to X;
  • Planetary environment preference > X
  • Previous building X already exists (in the Empire | on the target planet)
  • Technology X has been discovered
  • Population > X
  • Infrastructure (to be detailed when Infrastructure is finished; likely 'Y meter > X) -Aq)

Excess PP works identically to excess RP: the 'last' project in the queue to get any PP takes the excess PP until it has enough to advance one turn. Any excess PP that is not used by any project is wasted. Any minerals contributing to unspent PP are refunded back to the Empire.

An interface shall be provided to manage all construction on the Empire-level, as well as an addition to the planetary interface that displays the buildings that can be built on that planet.

Some method of limiting the amount of production points used to build ships will be applied to v0.4. Shipyards are likely to have their own set of rules determining the total number or maximum size of ships they can build. [b]Should there be something here about events or meters affecting the amount of PP pooled, e.g. a 'graft' penalty likely to appear in some version in which some percentage of your Imperial PP goes away due to piracy, racial traits, etc.? (Heavy Foot of Government, anybody?)

Building Effects

Buildings (and events) have effects on game objects as outlined in the Effects Document. Effects are a works-in-progress and the specific details and their implementation will evolve along with this document.

Section VIII. Research & Technology

The following section describes the system used to manage research and technology.

  • Technology is organized horizontally into some number of categories (assume an average of 10; changing categories should be mod-able, but a fixed number will be determined for v0.31.
  • Technology is ordered vertically by theory and then application, e.g. a 'Capital Ship' category might have 'Large-scale propulsion' as a theory and 'battleship engine' as an application. More specifically, theories are required to research their related, child applications; as a general rule, theories will not do very much by themselves, but this is a breakable rule.
  • Technology has a fixed cost, both in research points and in number of turns required. If an Empire produces 100 RP a turn, it may begin ten separate 'projects' that cost 10 RP. You may not invest 12 RP or 50 RP in one project for a faster result. Each of those 10 projects may have a different number of turns associated with it. The amount of time required is fixed in the sense that more RP will not change it, but it is not fixed in the sense that some technologies may reduce the time requirement for future technologies, or there may be some event that finishes one of your projects.

Excess (or unallocated) RP is kept in a persistent container until that container holds enough RP to advance a project by one turn. For example, if an Empire produces 105 RP per turn and has 11 projects requiring 10 RP per turn for 10 turns, the 11th project will advance 'one turn' every two turns such that it would be completed in 20 turns, given a constant input of 100 RP.

Excess RP beyond the requirements of currently active projects is wasted.

User interface requirements: A single screen to manage and prioritize projects and, at the discretion of the graphics team, anything from a line of text to a popup to an animated sequence that occurs whenever research is completed on a project. A mechanism shall be provided through which the player may prioritize projects; for example, there is nothing to prevent a player from starting 300 RP worth of projects even if there is only 100 RP available, but the projects must be ordered such that the system knows where to allocate new RP as it becomes available.

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. Resolve any combat. 3. Check for empire elimination and game end conditions. 4. Update research totals. 5. Update planet population production totals. 6. Place any newly built ships and buildings. 7. etc.

General Interface

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 a starlane 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.

Research & Technology

A screen accessible from the universe view shall display a list of technology categories (forthcoming); clicking on a category will display all theories and applications belonging to that category. Technology that has been researched will be highlighted separately from technology that has not. Clicking on a particular technology will display the RP cost per turn, all pre-requisites for that technology as well as all technology for which the currently selected item is a pre-requisite. There will also be space provided for a graphic representation of the technology and a written description (UI size and space allocation for each to be determined). The main research screen will also provide: the current RP production of the Empire and how much of it is being spent; a list of currently ongoing projects and highlight projects that are receiving fewer-than-requested RP separately from those that are fully underway; projects receiving no RP shall be highlighted separately from those. A mechanism will be provided to allow the player to prioritize and cancel projects.


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.