-
-
Notifications
You must be signed in to change notification settings - Fork 0
Reference
This document aims to provide a comprehensive reference for all components involved in modding Sunless Sea. It is specifically designed for use with SDLS and is not compatible with the vanilla version of Sunless Sea. This reference is heavily based on this excellent reference document created by Exotico.
Components will be referred to by their internal names, regardless of singular or plural forms. For example, qualities.json contains qualities components. Some components may directly reference another component, such as DefaultEvent, which is a direct reference to the events component, but they will be referred to by their base name instead of what they reference. The capitalization of components will always align with their internal names, except when derived from filenames, which may have context-based capitalization. For example, events.json > Events, UseEvent > UseEvent.
Events represent stories and are the main way you interact with the game. They are organized in a tree-like structure, with events leading to their child events. When you see an event displayed at a location in the game, it's called a storylet. Events live in entities/events.json.
Fields in other components that use/reference the events component:
- LinkToEvent
- DefaultEvent
- RareDefaultEvent
- SuccessEvent
- RareSuccessEvent
- UseEvent
Any component that references events does not require an Id, except for LinkToEvent and UseEvent, which only require an Id.
| Field | Description |
|---|---|
| Id | The unique Id of the event. See Id availability for availability. |
| Name | The name of the event. |
| Description | The text body/description of this event. See text formatting for formatting options. |
| Image | The filename of the image associated with this event. See image formatting. |
| Urgency | How urgent the event is and whether you can avoid it. Set to "Must" to autofire and remove the "Perhaps Not" button. |
| QualitiesAffected | An array of QualitiesAffected components which determines which qualities this event affects and how. Cannot be set on a non-autofire root event. |
| QualitiesRequired | An array of QualitiesRequired components which determines which qualities this event requires. |
| ChildBranches | All options that can fire from this event. Accepts an array of ChildBranches components. |
| MoveToAreaId | The Id of the area to which the character should be moved when this event fires. Must be zero for non-autofire root events. |
| SwitchToSetting | Changes the characters' Setting value when this event fires. Cannot be set to a non-null value on non-autofire root events. Accepts an empty SwitchToSetting component with an Id. {"Id":number}. |
| LimitedToArea | The area this event is able to appear in. Accepts an empty LimitedToArea component with an Id. {"Id":number}
|
| Setting | The setting this event can appear in. Similar but different to LimitedToArea (additional documentation needed). |
| ExoticEffects | The exotic effect to execute when exiting the event. Format is "[ACTION],parameter1,parameter2,...".Options: - "[CHANGE_TERRAIN], Location/OldTileName,Location/NewTileName" (used in Hunter's Keep's and the Zeppelins' transformation)- "[MOVE_TO_PORT], PortName"- "[GAME_END_EFFECT_WIN]" - "[GAME_END_EFFECT_LOSE]" - "[SELECT_AVATAR]" (used after picking an "Addressed As") - "[SELECT_LEGACY]" - "[SPAWN_BEASTIE], EnemyName"- "[FIGHT_BEASTIE], EnemyName" Possibly a remnant of the old combat system(?)- "[CHANGE_CURRENT_SHIP]" |
| Ordering | Where in the list of all events this event will appear. Higher numbers are displayed first. |
| LinkToEvent | The event this event should link to upon pressing the continue button. Accepts an empty LinkToEvent component with an Id. {"Id":number}
|
| Deck | Determines whether certain events are always available, or only available sometimes, dependant on Distribution. Accepts "Always" or "Sometimes", defaults to "Always". {"Availability":"Sometimes"}
|
| Distribution | Determines how frequent an event is if the Availability of its Deck is Sometimes. Accepts a number between 1 and 100. |
| Category | Determines the storylet color and some special effects. Options: - "Unspecialised"(default) - "Ambition" (silver) - "Episodic" (Plays a transition sound, stops music. Bronze.) - "QuesticleStart" (Plays a transition sound, stops music. Red.) - "QuesticleEnd" (bronze) - "Gold" (gold) - "Seasonal" (blue) |
| LogInJournalAgainstQuality | Should technically create a log component based on this event and the specified quality, but this is untested. |
Note: Due to limitations in Sunless Sea and SDLS 1.5.0 (current) and below, only 1 mod can edit any title event.
Qualities represent goods, statuses, progression, ships, and much more. Basically, if you can "have" it, it's a quality. Qualities live in entities/qualities.json.
Fields in other components that use/reference the quality component:
- AssignToSlot
- AssociatedQuality
- PurchasedQuality
- Quality
| Field | Description |
|---|---|
| Id | The unique Id of the quality. See Id availability for availability. |
| Name | The name of the quality. Some names are used as identifiers, so changing them may cause issues. Examples include: Luck, Memoirs: Your Past, Addressed As, A stranger, Memoirs: Quality of Lodgings, Hull, Terror, Almost Safe. Possibly more. |
| Description | The text displayed when hovering over the quality in the Gazetteer. See text formatting for formatting options. |
| Image | Name of the image file in the images folder. See image formatting. |
| Notes | Unused, but can be used for personal notes. |
| Tag | Used to tag DLC for display on account management screen. Useful for organizing your mod. |
| Enhancements | A list of qualities whose values this quality alters when equipped. Requires an array of Enhancements. Enhancements do nothing when the quality is not equipped. |
| AvailableAt | Adds a tooltip to the quality viewable on hover. Unsupported for the goods category (?). Example: Unrecruited officers. |
| Ordering | Determines position in lists. Lower numbers are displayed first. |
| Persistent | Whether the quality persists between captains. |
| UseEvent | Event triggered by interacting with this quality. Requires an empty UseEvent component with an Id. {"Id":number}
|
| DifficultyTestType | Determines success chance calculation method. Accepts "Broad" and "Narrow". See QualitiesRequired. |
| DifficultyScaler | Used in success chance calculations. |
| Nature | The general class of a quality. "Thing", "Status" or "Unspecified". |
| Category (Status) | More specific classification of quality type when Nature is "Status". Possible values: - Unspecified - Circumstance Example: Romance: an Affair with... - Story - Progress Example: Progress Of A Nation - Quest Only used by Searching for a Hero - Accomplishment Example: Scion - BasicAbility Example: Crew - SpecificAbility Only used by Luck - MinorLateral Only used by Addressed As These will determine certain attributes of the quality, such as where it is displayed. |
| Category (Thing) | More specific classification of quality type when Nature is "Thing". Possible values: - Companion - Goods - Ship - Curiosity These will determine certain attributes of the quality, such as whether it takes up hold space. |
| LevelDescriptionText | Unique descriptions for different quality levels. Format: "level|description~level|description". Example: Something Awaits You. |
| ChangeDescriptionText | Text displayed in the Gazetteer when quality changes. Format: "level|description~level|description". Example: Something Awaits You. |
| LevelImageText | Changes the image based on level. Format: "level|image~level|image". Example: Memoirs: Your Own Sweet Skin. |
| AssignToSlot | Slot to which quality can be assigned/equipped. Accepts an empty AssignToSlot component with the Id of the slot. {"Id": number}. Qualities can be equipped to the following slots:- Deck 102966 - Forward 102968 - Auxilary 102967 - Bridge 102964 - Aft 102965 - Engines 102904 - First Officer 102769 - Chief Engineer 102770 - Cook 102771 - Surgeon 102772 - Mascot 102774 - Gunnery Officer 102775 - Current Ship 102889 |
| UsePyramidNumbers | Attaches levelling system to qualities. Not supported for the Goods category. Example: Favours: Antiquarian. |
| PyramidNumberIncreaseLimit | Linked to UsePyramidNumbers. Level cap past which quality must increase by the level cap per level gained. |
| Cap | Maximum possible level for a quality. Not supported for Goods category. Examples include Stats and Terror. |
| LimitedToArea | Area where quality can be equipped/unequipped. (Unused in the basegame, possibly non-functional?) |
| AllowedOn | Determines what kind of possessor can hold this quality. "User" is for special things like DLC related qualities (You most likely won't use this). |
| IsSlot | Determines if quality is a slot for other qualities (You most likely won't use this). |
Enhancements represent a list of qualities the currently equipped quality (an officer, ship equipment, etc) will influence, and by how much. Enhancements can alter any quality in the game, although some qualities, like Echoes, will have unintended consequences. A qualities' Enhancements have no effect when it is unequipped. Enhancements live inside qualities in entities/qualities.json.
Tip: You can give an unequippable quality enhancements for flavour ;). For example, that's how the Snow Child got his heart.
| Field | Description |
|---|---|
| Level | The level by how much this quality is affected. |
| AssociatedQuality | The quality affected. Accepts an empty AssociatedQuality component with an Id. {"Id": number}
|
ChildBranches represent the choices available within the story tree of an event. Each ChildBranches component appears as an option when viewing an event. ChildBranches live inside events in entities/events.json.
| Field | Description |
|---|---|
| Name | The name of the branch. |
| Description | The description of the branch.See text formatting for formatting options. |
| DefaultEvent | The event that fires if you lose the branch's challenge, or none is provided. Accepts a DefaultEvent component. |
| RareDefaultEvent | An alternate event that fires based on RareDefaultEventChance. Accepts a RareDefaultEvent component. |
| RareDefaultEventChance | The chance RareDefaultEvent fires, between 1 and 100 (inclusive). |
| SuccessEvent | The event that fires if you succeed at the branch's challenge, or none is provided. Accepts a SuccessEvent component. |
| RareSuccessEvent | An alternate event that fires based on RareSuccessEventChance. Accepts a RareSuccessEvent component. |
| RareSuccessEventChance | The chance RareSuccessEvent fires, between 1 and 100 (inclusive). |
| QualitiesRequired | The qualities necessary for this event. This can include: - qualities required for the event to be visible. - qualities required to activate the event. - qualities utilized in the event's challenge. All of these can be used simultaneously. |
| ButtonText | Text displayed on the button of this branch, instead of Go and Locked if omitted. |
| Ordering | Determines the position of this branch in the list of options. Lower numbers are displayed first. |
| Archived | Makes the event completely invisible forever (You most likely won't use this). |
QualitiesRequired represents all the qualities the player must posess to interact with an event, and at what level. QualitiesRequired can be used to add an event challenge, gate access to an event or completely hide it. QualitiesRequired live inside a ChildBranch, as an array of components.
| Field | Description |
|---|---|
| AssociatedQualityId | The Id of the associated quality. |
| DifficultyLevel | Used in the formula for determining the chance of success based on the AssociatedQuality's DifficultyTestType and DifficultyScaler. The chance of success is calculated as follows: - Narrow: 50 + DifficultyScaler(QualityLevel - DifficultyLevel)% or 10%, whichever is higher.- Broad: (QualityLevel * DifficultyScaler) / DifficultyLevel% chance of success. |
| DifficultyLevelAdvanced | Determines the chance of success based on the number returned by evaluating an expression. See Advanced Expression. |
| VisibleWhenRequirementFailed | Whether or not to display the branch if the quality requirement is not met. |
| MinLevel | The minimum level of the quality required (inclusive). |
| MaxLevel | The maximum level of the quality required (inclusive). |
| MinAdvanced | Advanced expression for minimum level. See Advanced Expression. |
| MaxAdvanced | Advanced expression for maximum level. See Advanced Expression. |
QualitiesAffected represent all the qualities that will be altered as a result of the current ChildBranches event, and by how much.
| Field | Description |
|---|---|
| AssociatedQualityId | The Id of the associated quality. |
| Level | The level by which to change the quality. |
| ChangeByAdvanced | Changes the level of the quality by the result of an expression. Overrides Level if non-null. See Advanced Expression. |
| SetToExactly | Sets the level of the quality to this value. Overrides ChangeByAdvanced and Level if non-null. |
| SetToExactlyAdvanced | Sets the level of the quality to the result of an expression. Overrides all other level change fields if non-null. See Advanced Expression. |
| OnlyIfAtLeast | Only execute the effect if the quality’s level is at or above this number. |
| OnlyIfNoMoreThan | Only execute this effect if the quality’s level is at or below this number. |
| ForceEquip | Automatically equips the quality if it is a (Nature -) Thing and has a valid EquipToSlot component. |
Exchanges represents all shops (and surprisingly, the shipyard) in a port. Shops sell goods and curiosity qualities, and shipyards sell ships! Exchanges live in entities/exchanges.json.
| Field | Description |
|---|---|
| Name | The name displayed at the top of the shops tab. |
| Description | The text body/description displayed below the shops tab name. See text formatting for formatting options. |
| Shops | Every single individual shop that is available at the current port. Accepts an array of Shops components. |
| SettingIds | An array of settings the exchanges will appear in. See Setting. Example: MARKET OF HUNGERS |
Note: Due to limitations in Sunless Sea and SDLS 1.5.0 (current) and below, only 1 mod can edit the exchanges at any particular port.
Shops represent the individual shops in exchanges. Shops trade any arbitrary quality for another. Any ship quality being sold in a store will appear in the shipyard instead. Shops live inside exchanges in entities/exchanges.json
| Field | Description |
|---|---|
| Name | The name of the shop. |
| Image | The image of the shop. See image formatting. |
| Description | The text body/description displayed below the shops name. See text formatting for formatting options. |
| Ordering | Where in the list of all shops this one should go. Lower numbers are displayed first. |
| Availabilities | Every single quality sold in the shop. Accepts an array of Availabilities components. |
Availabilities represent individual qualities available in shops. Availabilities are sorted by Cost, with lowest cost being highest on the list.
| Field | Description |
|---|---|
| Quality | The quality you are purchasing. Accepts an empty Quality component with an Id. {"Id":number}
|
| PurchaseQuality | The quality you are paying with. Accepts an empty PurchaseQuality component with an Id. {"Id":number}
|
| Cost | The price of the Quality set in PurchaseQuality. Set to 0 to disable entirely. |
| SellPrice | The sell price of the Quality set in PurchaseQuality. Cannot be disabled, even if set to 0. |
Combat Constants largely govern variables related to combat and enemies. Beastie in this context means any enemy vessel or creature. Combat Constants live in constants/combatconstants.json.
| Field | Description |
|---|---|
| UnsuccessfulPathsLimit | Maximum failed pathfinding attempts allowed before the beastie is removed or reset. |
| SearchDuration | The amount of seconds for which a beastie actively searches for the player ship. |
| EvadeDuration | The amount of seconds that a beastie spends evading a threat. |
| RammingDuration | The amount of seconds a beastie spends trying to ram the player ship. |
| RammingMovementBonus | Speed boost applied to beasties while trying to ram the player ship. |
| BeastieChaseRange | Distance within which a beastie will keep actively chasing the player ship. |
| BeastieSneakLeadDistance | Distance a beastie maintains when sneaking up on the player ship during HuntingPlus behaviour. |
| SneakingDuration | The amount of seconds that a beastie spends sneaking towards the player ship. |
| SneakingTransitionLength | The amount of seconds to transition into sneaking mode. |
| SneakingMovementBonus | Speed boost for beasties while in sneaking mode. |
| IronDamageCoefficient | Value used in the following formula to calculate how much Iron affects your attack damage: damage + (IronStat * IronDamageCoefficient)
|
| MirrorsWarmupCoefficient | Value used in the following formula to calculate how much Mirrors affect your warmup time: BaseWarmUp - (MirrorsWarmupCoefficient / 25) * Mirrors (approximated formula) |
| VeilsAggroCoefficient | Value used in the following formula to calculate how much Veils affects the beasties' AwarenessRange: AwarenessRange - (VeilsAggroCoefficient * Veils)
|
| AggroRangeLightsOffModifier | Modifier for aggro range when the prow-lamp is turned off (applied before Veils bonus): AwarenessRange * AggroRangeLightsOffModifier
|
| IlluminatedWarmupCoefficient | Multiplier affecting warmup times of attacks when you or a beastie is illuminated. |
| BeastieMinPercentHitChance | Minimum hit chance percentage for a beastie's attacks. |
| CrewDamageHullThreshold | Hull damage threshold after which incoming attacks affect crew numbers. |
| DamageVariationRange | Range of variation applied to damage values for attacks. - MinAttack = Round(damage - (damage * DamageVariationRange))- MaxAttack = Round(damage + (damage * DamageVariationRange))
|
| MaxDistanceShuttlersWillChase | Maximum distance a neutral vessel will chase its target. Testing required. |
| BeastieItemUseInterval | Interval in seconds for how often a beastie uses items. |
| MinExoticSpawnRadius | Minimum radius around your ship where summoned exotic beasties can spawn. |
| MaxExoticSpawnRadius | Maximum radius around your ship where summoned exotic beasties can spawn. |
| ChanceOfFleePercentage | Should function as a percentage chance that a beastie will flee, but this was never implemented, and the beastie attacks instead. |
| StaticBeastieAttackRange | Maximum attack range for beastie attacks while in the Dormant Static behaviour state (most likely the state enemies are in while off-screen). |
| StaticBeastieAwakeTime | The amount of seconds it takes for a Dormant Static beastie to awake. |
Note: Due to limitations in Sunless Sea and SDLS 1.5.0 (current) and below, only 1 mod can edit the constants.
Navigation Constants largely govern variables related to navigation, stats and resource management. Gloom in this context is a semi-hidden stat and can be seen as a milliTerror (0.1 Terror). While some fields specify they affect Terror, they may instead influence Gloom, which indirectly increases Terror upon reaching its cap. Gleam in this context is a hidden variable that tracks the amount of light the ship is in. Navigation Constants live in constants/navigationconstants.json.
| Field | Description |
|---|---|
| HungerUpdatePeriod | Interval in seconds for updating hunger. |
| FuelUpdatePeriod | Interval in seconds for updating fuel consumption. |
| SomethingAwaitsYouPeriod | Time in seconds between awarding "Something Awaits You". |
| BaseHungerIncrease | Amount of hunger each crew member adds. |
| BaseShipSpeed | Base speed of any ship, regardless of engine power. Used in the following formula: BaseSpeed + ((EnginePower * EnginePowerModifier - ShipWeight) * BaseSpeedLimit) (cannot be lower than 1). |
| BaseShipSpeedLimit | Scales the impact of EnginePower and ShipWeight on speed. Higher values increase their effect, while lower values make BaseShipSpeed more influential. |
| ShipReversePenalty | Speed reduction multiplier applied when the ship is moving in reverse. |
| EnginePowerModifier | Multiplier applied to engine power. |
| BaseShipAcceleration | Value used in the following formula to control the ships acceleration: (TargetSpeed * TurboMultiplier * (IsReversing ? ReversePenalty : 1) - Speed) * deltaTime * (BaseShipAcceleration / SpeedIncrementUnit) + Speed * deltaTime.The ternary (?:) checks if the ship is reversing; if true, it applies ReversePenalty, otherwise it uses 1. |
| BaseShipTurningSpeed | Value used to calculate the turning speed of the ship. |
| EngineFuelDecrementUnit | Amount of fuel consumed by the engine per engine power. |
| LightFuelDecrementUnit | Amount of fuel consumed by the prow-lamp. |
| SonarRadius | Detection radius of the zub's sonar. |
| SonarPulsePeriod | Interval in seconds between sonar pulses. |
| SonarPulseInterval | Duration of each sonar pulse in seconds. |
| DiveTime | Time it takes in seconds for the ship to zubmerge and transform into a zub. |
| SkeletonCrewDivision | Determines at what percentage of crew your ship has a "skeleton crew", and cannot zail at full speed. Best interpreted as 100% / SkeletonCrewDivision. Completely unrelated to the skeleton crew required when boarding a vessel. |
| CrewLonelinessDivision | Determines at what percentage of crew your Terror starts to increase faster. |
| TerrorLonelinessMultiplier | Multiplier affecting Terror accumulation when under the CrewLonelinessDivision threshold. |
| TurboSpeedMultiplier | Speed boost multiplier applied to your ship's target speed during turbo mode. |
| TurboFuelCostMultiplier | Fuel consumption multiplier during turbo mode. |
| TurboPeculiarNoiseIncrease | Amount by which the Peculiar Noises quality should increase during turbo mode. |
| GloomUpdatePeriod | Interval in seconds for updating Gloom. |
| GloomUpdatePeriodInLight | Interval in seconds for updating Gloom while in light. |
| GloomUpdatePeriodUnderwater | Interval in seconds for updating Gloom while underwater. |
| GloomThreshold | Amount of Gloom required to increase Terror. |
| BaseGloomIncrease | Value used in the following formula to change gloom levels based on Gleam. Gloom = - Gleam 0: Gloom + (BaseGloomIncrease * 2 * TerribleLonelinessMultiplier)- Gleam 1: Gloom + (BaseGloomIncrease * TerribleLonelinessMultiplier)- Gleam 2: Gloom - BaseGloomIncrease
|
| GleamCheckRadius | Radius around the ship in which checks are performed for Gleam-boosting objects. |
| BaseTerrorIncrease | Amount of Terror added when Gloom reaches the threshold. |
| BaseGleamIncrease | How much Gleam is added by the lighting condition. Bright: + BaseGleamIncrease * 2, Dim: + BaseGleamIncrease. |
| DimAmbientThreshold | Threshold for the dim ambient light condition. |
| BrightAmbientThreshold | Threshold for the bright ambient light condition. |
| HeadlightGleamBonus | Bonus to Gleam for using the ship's prow-lamp. |
| PortGleamBonus | Bonus to Gleam when near a port. |
| RepairMinHullPercent | Minimum hull percentage required before you can do emergency repairs at Zee. |
| RepairUpdatePeriod | Interval in seconds for updating repair progress. |
| RepairSuppliesConsumed | Amount of supplies consumed per repair. |
| RepairHullIncreased | Hull percentage restored per repair. |
| SomethingAwaitsDateTimeIncrease | Amount of days to add to the ingame calender when "Something Awaits You" is awarded. |
| LegacyDateTimeIncrease | Amount of days to add to the ingame calender after you die/retire and choose a new legacy. |
| DefaultTileMappingRules | Default tile-preset used for creating a new chart (non-functional for unknown reasons, testing required). |
| MaxTradeEntityPopulation | The maximum amount of neutral trading vessels that can be on the map at once. |
| WeatherDurationInDays | Duration of weather effects in ingame days. |
| AllowCameraRotation | Whether the camera rotates with the ship's rotation. Does not rotate ingame text like landmark text and location names. |
| MaxOxygen | Maximum oxygen level of your zub. |
| OxygenIntervalUnit | Amount of oxygen to consume per second (?). |
| OxygenTerrorMultiplier | Contrary to its name, this value does not multiply oxygen usage at higher terror, but instead replaces OxygenIntervalUnit in the formula when at higher terror. |
| OxygenSurfaceMultiplier | Amount of oxygen to add to your zub when on the surface. |
| CurrentsForce | Strength of ocean currents when in a zub. |
| WitherweedSpawnChance | Percentage chance for witherweed to spawn in a tile. |
| InteractableDurationInDays | Duration in ingame days for certain interactable objects to remain active. (Testing required, it is unclear when the function that removes Interactables is run) |
Note: Due to limitations in Sunless Sea and SDLS 1.5.0 (current) and below, only 1 mod can edit the constants.
To ensure compatibility and prevent conflicts, it's recommended to use Id numbers above 600000 for custom content. All vanilla game Ids are below this threshold (with the highest being 561528). The maximum allowable Id value is 2,147,483,647 (MaxInt).
Some fields, usually descriptions, support text formatting. The following options are available:
-
\r\nfor line breaks ↩ -
[text]for green text, preceded and followed by a linebreak -
<i>text</i>for italics -
<b>text</b>for bold -
<color=#HEXff>text</color>for colored text (where HEX is a 6-digit hex color code) - Possibly more HTML-style tags
Image filenames should be the base name of the image, excluding the extension (.png) and context-specific suffixes like 'gaz' or 'small', which are automatically added by the game. For example, if your images are named "myimage.png", "myimagesmall.png" and "myimagegaz.png" you would specify just "myimage" as the filename in your JSON.
Setting is an arbitrary* value used by several functions of the game, most importantly, shops. Docking at a port will change the current setting, and thus the current shops. Shops can also be made to appear and disappear by events changing the setting. Events can set the current setting arbitrarily using SwitchToSetting. Events can also be set to appear in certain settings (untested).
* An arbitrary value refers to a value that, while set and used by the game, is not directly linked to any specific purpose. Docking at a port will change your setting value, but changing your setting value will not move you to a different port.
Determines the chance of success based on the number returned by evaluating an expression. There are three custom expressions that can be used:
-
[d:int]- generates a random number between 1 and int (inclusive). -
[q:Id]- gets the effective level of the quality with the given Id. This includes any temporary enhancements, like those of officers and equipment. -
[qb:Id]- gets the unmodified level of the quality with the given Id. This does not include any temporary enhancements.