Ship design definition

The definition of a ship design is the list of ship parts which are needed for the construction of a specific type of ship. Such a definition includes a hull, at least one engine, and it may include an arbitrary amount of other ship parts (generators, weapons, defences and any other kind of stuff).

Three constraints on valid ship designs exist:

• the total energy consumed by the various parts must be lower than or equal to the amount of energy generated by included generators,
• the total space consumed by the various parts multiplied by a “miniaturisation factor” (and empire-wide production) must be lower than or equal to the space provided by the ship’s hull,
• the ship must have a non-zero normal space thrust.

Predefined ship designs

The game includes a set of predefined ship designs. A predefined ship design is a ship design definition associated with a name and description from the internationalisation system. Since all predefined ship designs are considered to be valid, the minimal miniaturisation factor for a predefined ship design can be computed directly from the list of parts.

Empire ship designs

An empire ship design is a ship design definition identified by a name and associated with an empire. It includes a free text description, as well as a flag that indicates whether the design has been declared as being obsolete. Empire ship designs may only be deleted if no ship is actually using the design. Their names or descriptions may be changed at any time, however the design definition itself may not be modified if there are ships using the design.

Ships

A ship is identified by an arbitrary sequence number. It is based on an empire ship design. It may be given a name for identification purposes. In addition, a ship possesses hit points which must be lower than or equal to the amount of maximal hit points defined by its design, and experience points, acquired when the ship participates in battles. Ships also include a status information which indicates whether they are available, being deployed after construction, being redeployed after movements or mode switches, being redirected, undergoing repairs, being refitted or decommissioned, and a penalty which indicates the time required for a ship in any non-available status to be available again.

Fleets

A fleet is identified by an arbitrary sequence number. It consists of at least one ship (all ships in a fleet must use designs belonging to the same empire, as this determines the fleet’s ownership). It may have a name for identification purposes. A fleet has an attack strategy and a defence strategy, as well as tactics settings (target selection criterion and target selection mode). The game update identifier at which each strategy was last changed as well as the game update identifier corresponding to the latest tactics adjustment are stored, to prevent players from constantly switching these values.

A fleet may be orbiting a planet. In this case, all fleets belonging to the same empire have a mode, which is either attack or defence. The game update identifier at which the last mode change occurred is stored, to prevent players from switching from attack to defence and vice-versa too rapidly.

Fleets that are not orbiting planets are moving fleets. Such a fleet has a planet of origin; however, this information is insufficient, as fleets may be redirected at any time. A fleet’s actual origin is either an in-system location (which consists in a planet and a distance indication, that last part being positive if the origin was in the direction of the star, negative if it was in the direction of outer space, or zero if the fleet’s movement originated from the planet itself) or an outer space location (a set of x and y coordinates expressed as real numbers, since the redirection may occur at any point when moving in outer space). The time elapsed since the last movement order is required to estimate the fleet’s current actual location. Finally, the requested fleet mode on arrival is included.

An empire is identified through its empire name. There may only be one empire using a name from a single account at any given time. An empire possesses various quantities of different resource types. These quantities are always greater than or equal to 0, as debts are handled by damaging fleets and buildings.

Research

An empire may have implemented a set of technologies, and it may also be researching technologies. For each technology being researched, it is necessary to know the amount of accumulated research points. A priority (low, normal or high) may be assigned to a technology being researched.

Empire-controlled planets

An empire may own planets. Each owned planet may be in the process of being abandoned, which implies knowing the amount of game updates left before actual abandon.

All planets currently or formerly owned by an empire still include the empire’s configuration of the planet. This “configuration” includes:

• the extraction priority for each type of resource,
• the default name, tactics (target selection criterion and target selection mode), attack strategy and defence strategy of fleets produced by the planet,
• the planet’s battle tactics (target selection criterion and target selection mode),
• the building priority for both the civilian and the military build queues.

Visited / known planets

The last known status of any planet visited or formerly owned by an empire is stored. In addition to the game update identifier at which the information was last obtained, this includes information about the planet’s population, buildings on the surface and, if the planet had been scanned for resources, the amount and type of detected resources. Fleet information is also included: for each empire possessing fleets at the planet, the amount of ships and current mode are retained.

Empire-level diplomacy

An empire may define two types of enemy lists: enemy empires and enemy alliances.

An empire may define up to 5 ordered trusted allies, which are other empires to which an empire grants the privilege to move its fleets. A trusted ally entry is either pending or validated. Each empire may also define a T.A. blacklist, the list of all empires which are not allowed to give an empire trusted ally status.

Alliances

An alliance is identified by an alliance name. It must have at least one member empire, and one of the member empires must be the alliance’s leader. In addition, an empire that is not a member of an alliance may be requesting to join one alliance. An empire may only belong to or be requesting to join one alliance at any given time.

Map
The map consists in two major entities: stellar systems and planets.

A stellar system consists in a pair of coordinates, representing the system’s location on the map.

A planet is found at a specific orbit of a stellar system (each system has 5 orbits). It is identified through an unique map object name and includes a picture identifier to be used when displaying the planet. A planet has a population; a portion of this population is happy, the rest isn’t.

Planets may feature any amount of resource providers (at most one per type of resource); each resource provider includes its maximal amount, current amount, extraction difficulty and regeneration factor.

In addition to basic information regarding a planet, its infrastructure and current tasks must be described.

Buildings

The infrastructure of a planet consists in a set of buildings. A building is associated to a specific planet and building type. The record includes the building’s current hit points, used to determine whether it should be destroyed or not, and affecting its production level.

Civilian queues

A planet may possess a civilian build queue which lists which actions are being performed with regards to the planet’s buildings. An civilian build queue entry is specific to a planet and is identified by its queue order. It indicates the type of work being performed (construction, repair, destruction) and includes information regarding the amount of work which was already processed.

Construction is associated with a type of building and a quantity of buildings to construct, as well as the amount of work which was already performed on the current building. Destruction and repair operations may be associated with either a type of building and a quantity (in which case the game update should select the most damaged buildings) or an actual building.

Repair and destruction operations are updated when buildings are destroyed by external causes (inability to pay for the buildings’ upkeep or battle damage).

Military queues

A planet may possess a military queue which lists which actions are being performed by the planet’s shipyards; military queues are only supported for planets actually owned by an empire. A military queue entry is specific to an empire-controlled planet and identified by its queue order. Each queue entry is associated with an action being performed (construction, repair, refit, decommission). There are two different types of military queue entries:

• some entries are associated with an empire ship design; these entries also include the amount of ships that should be affected by the action (this information is updated as ships are processed),
• some entries are associated with an actual ship.

In addition, ship refitting operations are associated with a second empire ship design which indicates the type of ship the operation will produce.

Banned names

A banned name is a 20-character string that has been banned by an administrator from ever being used in any type of name.

Empire names

An empire name consists in an unique, 20-character string. It is associated with the account that created it. In addition, empire names need to be inspected by the administration team. Once an empire name has been inspected, it is associated with the administrative account which inspected it, the time and date of the inspection as well as whether it was reset or kept.

Alliance names

An alliance name actually consists in two strings: the tag, a 5-character string which uniquely identifies the alliance, and the description, a 40-character string which does not need to be unique. They are associated with the account owning the empire who created the alliance. Alliance names need to be inspected by the administration team – if a name is rejected, the alliance is disbanded. If it is validated, however, the administrative account which inspected it as well as the time and date of the inspection are associated with it.

While an alliance’s tag cannot be changed, its description may be modified by the alliance’s current leader. When that happens, the previous validation information is removed and the “account to blame” is updated accordingly.

Map objects names

A map object name is, at the moment, the name given to a planet. It consists in the actual name (which is a 20-character string), originally generated by the game when creating the map. To prevent players who just gained control on a planet from renaming it immediately, the minimal next renaming time and date are associated with name records and updated every time the corresponding map object changes owner or when the object is renamed.

When a map object name is changed by a user, it must be validated by an administrator, who may choose to keep it or to reset it. A map object name that was reset must still undergo the wait until the minimal next renaming time. Changing an already validated map name removes the inspection information.

Administrators

An administrative account is an account to which special privileges (stored through a bit mask) are given. Administrative accounts are identified by a name and can connect to a specific administration interface using a password (which must differ from the administrator’s “normal” password), for which a SHA1 hash and a MD5 hash are stored.

Administrative log

In order to make administrators accountable for their actions, a log of all administrative actions is kept. An administrative log entry consists in a time and date, a log level and a message. Each log entry is linked to the administrator whose actions are being logged. Administrative log entries are purged on a regular basis by the game server.

The banhammer

The “banhammer” (which is the tool used to ban users from the game) is more complex that the name would indicate. In the description below, “an administrator” means “an administrator with the proper privileges”.

A ban request is emitted by an administrator regarding a validated account. The request includes a reason why the account should be banned, as well as the time and date at which it was emitted. There can be only one ban request for a given account at any time; in addition, it is impossible to request a ban on an account which is already banned.

If no action is taken within one week (that is the default value, as determined by the game’s parameters – it may change within a single run of the game) of a request’s emission, the request is archived. Its expiration time and date are stored.

A ban request may be rejected by any administrator, including the administrator who initially requested the ban. When this happens, the request is archived, along with the time and date at which it was rejected and the reason for which it was rejected.

Finally, a ban request may be validated by an administrator (as long as the validating administrator is not the one who originally requested the ban). In this case, the time and date at which the request was validated, as well as the validating administrator are stored. The account becomes banned as soon as the request is validated.

If the account that was banned was still active, it is “redeemable” for the next 48h – the associated empire is not deleted. After 48h, or if the account was originally disabled, it becomes fully banned. In any case, a ban may be lifted, in which case the ban request is archived (along with the time and date at which it was lifted) and the account is returned to its previous state.

Accounts

An user account is identified by its e-mail address. It may authenticate using a password whose SHA1 hash and MD5 hash are associated with the account.

The state of an account changes over time, depending on player actions and administrative action, as shown by the diagram below.

The various states of an account and transitions between these states.

When an account is first created, the only possible action is to validate it. This validation is performed through a validation key (a random, 64-character string). Accounts that have not been validated have an expiration date and time past which they are deleted.

All validated accounts have some arbitrary amount of game credits, which may be used to “buy” extra features. In addition, currently active accounts accumulate vacation credits which can be used to enter vacation mode.

Accounts which have been disabled as well as active accounts which are being disabled by their owners are associated to the time and date at which the account was (respectively “will be”) disabled. They may include a reason – a short text from the user explaining why he chose to disable his account.

The owner of a disabled account may request its re-activation. This is done using a new validation key which, if not used within some time, will expire (the account would then return to its previous state).

An active account may be entering vacation mode or in vacation mode. In both cases, the date and time at which vacation mode will be / has been enabled needs to be stored.

An active account to which there has been no connection for the past 3 weeks enters the unused state, at which point an e-mail is sent; the date and time at which the e-mail is sent is stored. If there has been no connection 1 week after the account entered the unused state, the account is disabled.

Extra features

An extra feature is some improvement to the game’s interface (e.g. tools, storage space) which may be “bought” by a player using game credits.

Feature definition

An extra feature definition is identified by a code name, which will be used to refer to the feature in the game server’s code; it is associated with a name and a description from the internationalisation system. An extra feature has a cost in game credits.

There are two types of extra features:

• features which may be bought include a maximal quantity (for example, it is possible to buy up to four T.A. list extensions) and a savings factor (which is applied when buying multiple features of a given type in one operation); in addition, such a feature may depend on another feature of the same type,
• features which use a subscription model do not include any additional information.

User features

A user feature is a feature that has been bought or subscribed to by the owner of an account.

M3 should also include some form of credits history

Sessions history

An entry of the sessions history is linked to an account. It stores the game server’s session identifier and IP address (for reference purposes), as well as the type of the session and the time and date at which the session was initialised. If the session is no longer active, the time and date at which it ended as well as the reason why it ended (manual disconnection, automatic disconnection because of exclusive sessions, expiration or server restart) are stored.

Warnings

Warnings may be given to an active account by the administration team. No warnings may be given in the hour after another warning has been given. In addition, warnings are removed after 2 months. Warnings are kept even if the account becomes disabled.

A warnings record is therefore associated to each user account that received at least one warning; the record stores the amount of warnings received, the date and time at which the last warning was received and the date and time at which the warnings count will be decreased (this value is initialised when a warning is received, and then updated when a new warning is received or when the counter is decreased).

User log

A log of all account-related actions is kept. An user log entry consists in a time and date, a log level and a message. Of course, such an entry is linked to an account. All entries pertaining to an account will be deleted when the account itself is deleted; logs are otherwise purged at a regular interval.

Password recovery requests

A password recovery request is associated with a validated account that requested it – there can only be one at any given time. Because the functionality could be used to “spam” the game’s users, requests on an account are locked for some time, even if password recovery is indeed validated. When such a request has not been validated yet, it also includes a recovery key – a random 64-character string.

Address change requests

An address change request may be requested by any active account. The new e-mail address must not be used by any other account (and it may not be used by any other address change request). To prevent users from using the address change system to “spam”, an address change request (whether it is confirmed, cancelled or simply ignored) expires after a few hours. Finally, pending address change requests are associated with a validation key (a random, 64-character string).

Preferences

In order to store user preferences, the database should store a list of preference definitions. A preference definition is identified by an unique code name and belongs to a preference group which is also identified by a separate code name (and features a display name and a description as strings from the internationalisation system). A preference definition also includes a name and a description (both being strings from the internationalisation system). The definition may correspond to a general preference, or be specific to a session type. Finally, a type identifier and a default value are associated with the definition. Both are actually strings, to be interpreted by the game server.

An actual user preference associates a user account with a preference definition and specifies the preference’s value.

Application status

Information regarding the application’s state include the identifier of the next game update, the identifier of the current game update if one is being processed at the time, the date and time at which each type of recapitulation e-mail was last sent (administrative, server errors, player messages), and information about maintenance mode, if enabled (start date & time, scheduled end date & time, reason).

System logs

Entries in the system log include a time stamp, a level (trace, debugging, information, warning or error), a component identifier and a message. In addition, a log entry may be associated with an exception record. Such a record includes the list of exceptions in the proper order, with the exception’s class and message, and the stack trace for each exception. An entry of the stack trace may contain a location (class and method), a file name and a line number.

Ticker status

The “ticker” is the server component which fires the various tasks that ensure the game’s proper functioning. A ticker task is identified by its name. It may be running, stopped or scheduled to start automatically at a later date and time.

Game update status

When the various game updates are being executed, it is necessary to store their current status in order to make sure that an error during a game update can be recovered from. Information regarding a game update includes the type of update (e.g. fleet movement, battle computations, empire research…), the last game update at which the update was last executed, and whether the update has been processed, is being processed, or is scheduled for processing. Finally, there are two major types of updates – updates which affect planets and updates which affect empires; this implies storing a reference to the planet or empire affected by the update, respectively.

Game and system parameters

A game or system parameter is identified by a code name (which is used in the game’s code to refer to the parameter). It possesses both a name and a description, which are stored as text (only administrators will see these strings). A parameter belongs to a category identified by a name. It may include a lower bound and / or a higher bound, and of course has a value.

Session types

The game will, in the future, allow for various types of sessions (in addition to sessions from the usual web interface). A session type is defined by a code (e.g. “web” in the case of the web interface), associated to a flag indicating whether the session type is exclusive. An exclusive session will automatically terminate any concurrent, exclusive session.

In this post:

• Internationalisation
• Resource types
  • Natural resources
• Types of weaponry and defences
• Production and capability types
• Technologies
• Fleet strategies
  • Defence strategies
  • Attack strategies
  • Relative strengths
• Stuff that can be built
  • Building types
  • Ship parts

Internationalisation

All text that is independent from the interface used to access the game is stored in the database. Each string is identified by a code, and associated to translations in various languages. Each language is identified by an ISO code and a name (in the language itself). The set of translations available in a given language may be incomplete, for example when a new language is being added.

All definitions which require a name or a description in fact use the internationalisation system.

Resource types

The various types of resources which empire may possess and use are defined in the database. Each resource type is identified by its name; in addition, it carries a description as another string from the internationalisation system. It belongs to a resource category, itself identified by yet another string. All resources are given a value which is used to compute e.g. player rankings. Finally, advanced types of resources only become visible when some technology has been discovered.

Natural resources

Some types of resources can be found in the game universe and can be extracted through mining operations. These natural resources are added to the map when it is generated. Each type of natural resource has a non-zero probability of being found at a location; in addition, the map generator should enforce an average quantity and average extraction difficulty.

Types of weaponry & defences

There are three categories of weaponry (beam weapons, mass drivers and missiles) and their respective countermeasures (shields, armours and point defence systems). Each weaponry or defence category should be identified by its general type and by whether it is a weapon or a countermeasure. In addition, a name and a description need to be associated with each category.

Production and capability types

Productions and capabilities, whether they apply to whole empires, planets or ships, are described in the exact same way.

Generally speaking, a production or capability is identified by a code name. It possesses a display name and a description. It carries a flag indicating whether it is an additive or exclusive property – for example, ship components providing automated repairs have an additive effect, while mineral scanners are either present or not.

The value of a production may not be meaningful to the player. In order to display that value, a production definition includes a non-zero display multiplier, and may use a prefix and / or a suffix. If there is a suffix, then a suffix tooltip text may be included. The prefix, suffix and suffix tooltip text are of course internationalised strings.

While empire and ship productions do not include any additional data, a planet production or capability definition features a flag that indicates whether the production is local or global. A local production is used at the planet’s level only, while a global production is computed at the owning empire’s level.

Technologies

A technology is identified by its name. It carries a description, and requires an amount of research points to be accumulated before it is discovered. Each technology belongs to a technology category, identified by its name. A technology has an implementation price, defined by at least one type of resource and a positive quantity. Finally, a technology may only be researched once its dependencies (a set of other technologies) have been discovered.

In addition, a technology may provide some amount of an empire production.

Fleet strategies

Generally speaking, a fleet strategy is described by a name and a description. In addition, all fleet strategies include a probability of intercepting shots to other fleets, an advantage threshold used to determine whether ground armies should be dropped to the planet’s surface, and an advantage multiplier which indicates how much support a ship of size 1 gives to the ground armies. All strategies also include a probability of changing targets.

Defence strategies

A defence strategy is a strategy which can be used by fleets in defensive mode. In addition to the common strategy information, it also includes a probability of intercepting shots to the planet.

Attack strategies

An attack strategy is a strategy which can be used by attacking fleets. In addition to the common strategy information, attack strategies also include information related to attacking the planet: a weight modifier for ground structures, which determines how likely a fleet using the strategy is to target the planet’s buildings; a military objectives modifier, which indicates how likely the fleet is to target civilian structures, and a civilian casualties modifier, which will be used to compute civilian casualties when firing at ground structures. In addition, because planets do not have strategies, the information regarding attack strategies’ relative efficiency opposed to planets is included along with attack strategies. This information consists in 4 modifiers: aim and damage modifiers for the fleets, and aim and damage modifiers for planets.

Relative strengths

Each combination of an attack strategy with a defence strategy is described through 2 sets of modifiers: aim and damage modifiers for both the attacking and the defending sides.

Stuff that can be built

The database should contain the definition of all “buildable” items. Such an item is always identified by a name; it is associated with a description, and its construction requires a positive amount of work. In addition, all items which can be built carry a construction price and a maintenance price, both being a non-empty set of resource types associated with positive quantities.

Building types

A building type is a buildable item. It generates at least one type of planet production, with a maximal quantity associated to each type of production. Each type of building provides a quantity of jobs to be manned by the planets’ population, and possesses a maximal amount of hit points.

Buildings may also provide planet-side weaponry. A building may be associated with a type of weapon, along with weapon characteristics – accuracy, base damage, charge time and cool-down time.

Ship part types

A ship part is a buildable item. It belongs to a ship parts category identified by a name (a category may be a sub-category of another category).

There are different types of ship part types, which correspond to major elements of a ship’s design.

Rationale regarding the hybrid direct/meta modelling of ship parts: some of the ship parts’ characteristics are essential in that they provide the basic description of a ship design; most of these characteristics are used as constraints during the design of a ship (for example, available hull space must be greater than / equal to the amount of used hull space multiplied by the empire’s miniaturisation capabilities). In addition, these basic characteristics should not change in further versions of LW. However, other characteristics corresponding to various special abilities are not necessary in most operations, and are likely to evolve as development progresses. The latter are stored using meta-modelling while the former are stored directly.

Hulls

A hull is a type of ship part which provides space for other parts. It is either mechanical or biological in nature, and defines the amount of hit points as well as the basic manoeuvrability of a ship. In addition, a hull may provide energy. Finally, it may provide ship capabilities in various quantities.

Generators

A generator is a type of ship part which consumes space in a ship’s hull and provides energy. It may require the ship to be mechanical or biological.

Normal space engine

A normal space engine is a type of ship part which consumes space in a ship’s hull and requires energy. It provides thrust. It may require the ship to be mechanical or biological.

Hyperspace engines

A Hyperspace engine is a type of ship part which consumes space in a ship’s hull and requires energy. It provides Hyperspace displacement power. It may require the ship to be mechanical or biological.

Hybrid engines

A hybrid engine is an engine that is both a normal space engine and a Hyperspace engine.

Weapons

A weapon is a type of ship part which consumes space in a ship’s hull and requires energy. It is associated with a weapon type, and possesses a charge time, a cool-down time, an accuracy value (which is a probability) and a base damage.

Countermeasures

A countermeasure is a type of ship part which consumes space in a ship’s hull and requires energy. It is associated with a defence type and possesses an absorption probability, a maximal absorption value and a per-minute absorption recovery value.

Other ship parts

Any other type of ship part is a ship part which consumes space in a ship’s hull and may require energy to function. It may provide ship capabilities in various quantities.

Summary of ship part “types” and associated information

The table below is a summary of the information required by the various “families” of ship parts listed above.

Here is a list of the various parts that will be posted. I will update this list by adding links to the relevant posts when they are published.

• Game definitions – data that is required to make the game work, but is never changed.
• Application data – data used to store the current state of the game server.
• Users – accounts and account management data.
• Administration – administrative accounts and related information.
• Naming – data regarding empire, alliance and map object names.
• Universe – the universe’s map and the planets’ states.
• Empires & alliances.
• Ship designs, ships and fleets.
• Battles – everything that has to do with storing battle reports.
• Communications – internal messages as well as player communications.
• Bug tracking system.

Before I start, two important precisions are necessary. First, while there is actual ground combat (which is quite different from previous versions), players have no direct influence over it – everything is based on fleet strategies, and there are no actual ground units. Second, this ground combat system is definitely not the final version, it will be rewritten for M3 when the “real” planet management system is added.

Origins of ground armies

Ground armies come from 3 different sources.

• The planet itself provides a ground army, whose size depend on the planet’s population and happiness at the beginning of the battle.
• Buildings may provide ground armies.
• All ships (both defensive and offensive) may carry ground army drop pods.

Advantage index

The advantage index is a value between 0 and 1 that determines which side has the advantage. It is initially slightly in favour of defensive armies. However, it is affected by ships and buildings on both sides. Each ship increases the advantage for its side by a value that is determined by its fleet’s strategy; of course, buildings provide a fixed, pre-defined advantage increase for the defenders. The closer the value is to 0.5, the less clear the ground situation is – casualties will be high on both sides. If the value gets close to 0, then the attackers gain the advantage and they can inflict massive damage without suffering too much in return. Of course, the situation is reversed if the value is close to 1.

Dropping and extracting armies

Ships carrying armies will drop or extract their armies depending on this advantage index and on a setting that is determined by the fleet’s strategy. For example, in the current simulations, attacking fleets drop their armies below 0.55 while defending fleets drop theirs above .3 (they will therefore defend as long as the situation isn’t too desperate). Of course, this does not apply to armies provided by the planet itself or by buildings, which will always be present on the planet’s surface.

Damage

Damage to ground armies is partially determined by the advantage index. It is also strongly affected by the armies’ size: a very small army will probably lose against a much bigger one, even if the advantage index is totally in its favour – while it will inflict quite a lot of damage to the big army and not lose much at each battle update, it will end up dead eventually.

In the case of ground armies provided by ships and building, any damage to the army will translate back to its “container”, and vice-versa (any damage to the ship or building will reduce the size of the army).

Conquest

A planet is conquered when defending ground armies have been killed. The major consequence of this is that it is now entirely possible to conquer a planet while the battle is still being fought in orbit. I am still hesitating about what to do when this happens regarding the status of fleets – the best thing being to make it a setting.

Next time…

Unless you have questions or suggestions, which you should post as comments, the next post will not appear for quite a while. It will be about the battle computation’s implementation or about the database’s structure in M2, whichever comes first…