# Documentation for *Gameplay*

## Overview

You can read more details about the [Research](Research.md.html) and [Colonists](Colonists.md.html) in their respective pages. Here are provided some useful functions for implementing gameplay effects. Modders could also create new [Technologies](ModItemTechnology.md.html), [Mission Sponsors](ModItemMissionSponsor.md.html) or [Commander Profiles](ModItemCommanderProfile.md.html).<br>

## BoostTech

Boost specific technology research speed by reducing the needed research points for it with given percent. Calling multiple times, sums percents before applying them.<br>

void **BoostTech**(string tech_id, int percent)
string tech_id
: technology id.

int percent
: boost persent change.


## BoostTechField

Boost technology research speed by reducing the needed research points of all technologies in that field with given percent. Calling multiple times, sums percents before applying them.<br>

void **BoostTechField**(string field, int percent)
string field
: technology field. Passing "" to that parameter sets boost percent for all technology fields.

int percent
: boost persent change.


## ChangeFunding

Change funding  by adding or removing any value(in millions).<br>

void **ChangeFunding**(int funding, [string source])
int funding
: +/- value in M 1M=1000*1000


## ChangeLabelModifier

Change an already existing label property modifier.<br>

void **ChangeLabelModifier**(string id, string label, string property, int new_amount, int new_percent)
string id
: modification identifier.

string label
: label affected by the modification. Label **cannot** be changed - you must remove the old modifier and create a new one.

string property
: property affected by the modification. Property **cannot** be changed - you must remove the old modifier and create a new one.

int amount
: new amount to be added to the property value (default=_0_).

int percent
: new percent change of that value (default=_0_).

See also: [CreateLabelModifier](#CreateLabelModifier) and [RemoveLabelModifier](#RemoveLabelModifier)<br>

## CreateLabelModifier

Create a modifer for a label property.<br>
A label property modifier looks up all objects within a _label_ and modifies one of their properties.<br>
The modification can add an absolute value _amount_ and a relative value _percent_ (_0-100_). Both can be positive and negative.<br>
You can create multiple modifiers for the same property of a label, but they **all must have unique IDs** (even between different mods).<br>
The final value of a property is calculated using the formula: _original * (100 + total_percent) + total_amount_.<br>

void **CreateLabelModifier**(string id, string label, string property, int amount, int percent)
string id
: unique modification identifier.

string label
: city label. e.g all buildings are listed in labels with their template_name and build menu category.

string property
: property of that label/class.

int amount
: amount to be added to the property value (default=_0_).

int percent
: percent change of that value (default=_0_).

See also: [ChangeLabelModifier](#ChangeLabelModifier) and [RemoveLabelModifier](#RemoveLabelModifier)<br>

## DiscoverTech

Discovers a tech, revealing it in the Research UI.<br>

void **DiscoverTech**(string tech_id)
string tech_id
: technology internal id.


## GrantResearchPoints

Instantly grant research points, as if a research center generated them.<br>

void **GrantResearchPoints**(int amount)
int amount
: amount of points to grant.


## GrantTech

Research technology and gain its effect. If the technology property 'repeatable' is set to true, it can be researched multiple times.<br>

void **GrantTech**(string tech_id)
string tech_id
: technology internal id.


## IsCropAvailable

Tests crop lock state controlled by LockCrop and UnlockCrop functions.<br>
<br>

bool ret **IsCropAvailable**(string crop_name)
string crop_name
: The template name of the crop.

_returns_ bool ret
: Whether the crop is unlocked.


## IsTechDiscovered

Check if a technology has been discovered.<br>

number **IsTechDiscovered**(string tech_id)
string tech_id
: technology internal id.

_returns_ 
: index of discovery or nil, if not yet discovered.


## IsTechRepeatable

Check if a technology can be researched multiple times.<br>

bool **IsTechRepeatable**(string tech_id)
string tech_id
: technology internal id.


## IsTechResearched

Get the number of times a technology has been researched.<br>

number **IsTechResearched**(string tech_id)
string tech_id
: technology internal id.

_returns_ 
: number of times this tech has been researched or nil, instead of zero.


## IsTraitAvailable

Tests trait lock state controlled by LockTrait/UnlockTrait functions.<br>
<br>

bool available **IsTraitAvailable**(string trait_name)
string trait_name
: internal unique trait name.

_returns_ bool available
: true if the trait is unlocked.


## IsVegetationPlantAvailable

Tests vegetation plant lock state controlled by LockVegetationPlant and UnlockVegetationPlant functions.<br>
<br>

bool ret **IsVegetationPlantAvailable**(string plant)
string plant
: The template name of the vegetation.

_returns_ bool ret
: Whether the vegetation plant is unlocked.


## LockBuilding

Locks a building from the build menu. This method ignores tech effects. Note that this method will override anything done to the same building by the "Control Building Prerequisites" sequence action.<br>
<br>

void **LockBuilding**(string template_name[, string lock_type, T disable_reason])
string template_name
: The template name of the building to be locked.

string lock_type
: Optional. Lock type can be "hide", where the building will not be visible in the build menu, "disable", where the building will be visible but not clickable. Any string different from "hide" and "disable" defaults to "hide". Omitting the value defaults to "hide".

T disable_reason
: Optional. If lock type is "disable" the rollover information string can be provided with this param. It has to be a localized string. If omitted will default to "This building has been disabled".


## LockCrop

Locks a crop from the crop selector. Once locked a crop will no longer be selectable for current and future farms until unlocked. Already selected crops are unaffected.<br>
<br>

void **LockCrop**(string crop_name, string lock_id)
string crop_name
: The template name of the crop to be locked.

string lock_id
: Lock id of the lock. For a crop to be unlocked all unique locks must be removed.


## LockImport

Locks an item from the list of available imports. Once locked an item will no longer be visible in the resupply interface until unlocked.<br>
<br>

void **LockImport**(string item, string lock_id)
string item
: The name of the item to be locked.

string lock_id
: Lock id of the lock. For an item to be unlocked all unique locks must be removed.


## LockTrait

Locks a trait - it is not visible in interfaces and can not be added to colonists.<br>
<br>

void **LockTrait**(string trait_name, string lock_reason)
string trait_name
: internal unique trait name.

string lock_reason
: the unique reason of the lock. Use it to unlock the trait. To unlock a trait all unique lock reasons must be removed.


## LockVegetationPlant

Locks a vegetation plant from the plant selector. Once locked a plant will no longer be selectable for current and future farms until unlocked. Already selected vegetation plants are unaffected.<br>
<br>

void **LockVegetationPlant**(string plant, string lock_id)
string plant
: The template name of the plant to be locked.

string lock_id
: Lock id of the lock. For a plant to be unlocked all unique locks must be removed.


## ModifyConstructionCost

Modify construction cost of  the specified building/category with the specified percent. Calling ModifyConstructionCost multiple times in one building with different percents, first sums all percents and then apply to the cost.<br>

void **ModifyConstructionCost**(string building_name, string construction_resource, int percent)
string building
: single buidling template name or buildmenu category for all buildings from that category.

string construction_resource
: one of construction resources (ConstructionResourceList = {"Concrete", "Metals", "Polymers", "BlackCube", "Electronics", "MachineParts", "PreciousMetals" }) or "all" for all construction resources.

int percent
: change the cost with that percent.


## ModifyResupplyParam

Change price or weight of resupply item. If called multiple times, first sums percents.<br>

void **ModifyResupplyParam**(string id, string param, int percent)
string id
: resupply item identifier.Can be

"RCRover","ExplorerRover","RCTransport", "Drone", "Concrete", "Metals", "Food", "Polymers", "MachineParts", "Electronics" "DroneHub","MoistureVaporator","FuelFactory", "StirlingGenerator", "MachinePartsFactory","ElectronicsFactory",  "PolymerPlant","OrbitalProbe","ShuttleHub", "MetalsExtractor",  "RegolithExtractor", "WaterExtractor", "PreciousMetalsExtractor","Apartments", "LivingQuarters", "SmartHome", "Arcology",  "HangingGardens","WaterReclamationSystem", "CloningVats","NetworkNode", "MedicalCenter",  "Sanatorium",<br>
string param
: type of change: "price", "weight" 

int percent
: percent to change with.


## ModifyResupplyParams

Change price or weight of all resupply items.<br>

void **ModifyResupplyParams**(string param, int percent)
string param
: type of change: "price", "weight" 

int percent
: percent to change with.


## RemoveBuildingLock

Unlocks a building in the build menu, but doesn't interfere with tech effects that may be locking it (in contrast to [UnlockBuilding](#UnlockBuilding)).<br>
<br>

void **RemoveBuildingLock**(string template_name)
string template_name
: The template name of the building to be unlocked.

See also: [UnlockBuilding](#UnlockBuilding)<br>

## RemoveLabelModifier

Removes an already existing label property modifier.<br>

void **RemoveLabelModifier**(string id, string label, string property)
string id
: modification identifier.

string label
: label affected by the modification.

string property
: property affected by the modification.

See also: [CreateLabelModifier](#CreateLabelModifier) and [ChangeLabelModifier](#ChangeLabelModifier)<br>

## UnlockBuilding

Unlocks a building in the build menu regardless of tech effects that may be locking it (in contrast to [RemoveBuildingLock](#RemoveBuildingLock)).<br>
<br>

void **UnlockBuilding**(string template_name)
string template_name
: The template name of the building to be unlocked.

See also: [RemoveBuildingLock](#RemoveBuildingLock)<br>

## UnlockCrop

Removes a lock or all locks from a crop. Unlocked crops will appear in the farm crop selector of all current and future farms.<br>
<br>

void **UnlockCrop**(string crop_name[, string lock_id])
string crop_name
: The template name of the crop to be unlocked.

string lock_id
: Optional. Lock id of the lock. For a crop to be unlocked all unique locks must be removed. If omitted all locks for the relevant crop will be removed.


## UnlockImport

Removes a lock or all locks from an import item. Unlocked item will appear normally in the resupply interface.<br>
<br>

void **UnlockImport**(string item[, string lock_id])
string crop_name
: The name of the item to be unlocked.

string lock_id
: Optional. Lock id of the lock. For an item to be unlocked all unique locks must be removed. If omitted all locks for the given item will be removed.


## UnlockTrait

Removes a lock reason or  all lock reasons from a trait. If all lock reasons are removed, the trait is fully unlocked and is available for setting to colonist.<br>
<br>

void **UnlockTrait**(string trait_name[, string lock_reason])
string trait_name
: internal unique trait name.

string lock_reason
: lock reason that is locked with. In not specified all lock reasons are removed and the trait is fully unlocked.


## UnlockUpgrade

Unlock upgrade so it is available for construction in all building types that has such upgrade id described in their building template.<br>

void **UnlockUpgrade**(string upgrade_id)
string upgrade_id
: Unique upgrade id set in upgrade definition in building templates.


## UnlockVegetationPlant

Removes a lock or all locks from a vegetation plant. Unlocked plants will appear in the vegetation plant selector of all current and future farms.<br>
<br>

void **UnlockVegetationPlant**(string plant[, string lock_id])
string plant
: The template name of the crop to be unlocked.

string lock_id
: Optional. Lock id of the lock. For a plant to be unlocked all unique locks must be removed. If omitted all locks for the relevant plant will be removed.





(insert footer.md.html here)
<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style>
<script src="markdeep.min.js"></script>
<script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script>
<script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>