Module:Ships data/doc - Revision history

76561197969631737: updated doc with enriched fields. added section on exported types.

2026-08-07T19:36:47Z

updated doc with enriched fields. added section on exported types.

← Older revision		Revision as of 19:36, 7 August 2026
Line 44:		Line 44:

	<pre>local flavour_text = ships_data.get_ship_class_description("Destroyer+")</pre>		<pre>local flavour_text = ships_data.get_ship_class_description("Destroyer+")</pre>

			== Types ==

			The module's exported functions and returned records are typed using [[mw:Lua reference manual\|LuaCATS]]-style annotations in the module's source. These aren't enforced at runtime, but document the exact shape of every value the module returns.

			=== ShipRecord ===

			A single ship's full data. See [[#Ship record shape\|Ship record shape]] below for field-by-field details.

			=== ShipResourceAmount ===

			A <code>{ resource, qty }</code> pair used in <code>construction_costs</code>.

			=== ShipCrewAmount ===

			A <code>{ type, qty }</code> pair used in <code>crew_types</code>.

			=== ShipStatAmount ===

			A <code>{ stat, qty }</code> pair used in <code>stats_base</code> and <code>stats_crew_bonuses</code>.

			=== ShipUnlockAmount ===

			A <code>{ path, qty }</code> pair used in <code>unlock_points</code>.

			=== ShipsDataModule ===

			The shape of the table returned by <code>require("Module:Ships_data")</code> — i.e. the functions documented above.

	== Ship record shape ==		== Ship record shape ==
Line 52:		Line 80:
	! Field !! Type !! Note		! Field !! Type !! Note
	\|-		\|-
	\| name \|\| string \|\| Display name		\| <code>name</code> \|\| string \|\| Display name
			\|-
			\| <code>tier</code> \|\| number \|\| 1..6, inclusive
			\|-
			\| <code>principle_path</code> \|\| string \|\| Primary Principle Path alignment of the class of ship
	\|-		\|-
	\| ~~tier~~ \|\| ~~number~~ \|\| ~~1..6~~, ~~inclusive~~		\| <code>class</code> \|\| string \|\| Primary class of the ship, with an trailing plus sign for hybrids, similar to their in-game display, for example "Notoriety"
	\|-		\|-
	\| ~~principle_path~~ \|\| string \|\| ~~Primary~~ Principle Path alignment of the class of ship		\| <code>hybrid_path</code> \|\| string \|\| Secondary Principle Path alignment of the class of ship, according to the unlock requirement on the Compass (never has a trailing plus sign)
	\|-		\|-
	\| ~~class~~ \|\| string \|\| ~~Primary class~~ of the ship, ~~with an trailing plus sign~~ for ~~hybrids, similar to their in-game display~~, ~~for example~~ "~~Notoriety~~"		\| <code>icon_filename</code> \|\| string \|\| The filename, including the extension, of the image of the ship, for example, <code>"T_Ship_Starter.png"</code>
	\|-		\|-
	\| ~~hybrid_path~~ \|\| string \|\| ~~Secondary Principle Path alignment of~~ the ~~class of~~ ship, ~~according to the unlock requirement on the Compass (never has a trailing plus sign)~~		\| <code>pier</code> \|\| string \|\| The pier required to build the ship, for example, "Shallow Pier"
	\|-		\|-
	\| ~~icon_filename~~ \|\| string \|\| The ~~filename, including the extension, of the image~~ of the ship~~, for example, <code>"T_Ship_Starter.png"</code>~~		\| <code>description</code> \|\| string \|\| The English-language flavour text of the ship
	\|-		\|-
	\| ~~pier~~ \|\| ~~string~~ \|\| ~~The pier required to build~~ the ~~ship~~, for example, "~~Shallow Pier~~"		\| <code>construction_costs</code> \|\| array of <code>ShipResourceAmount</code> \|\| pairs of <code>{ resource, qty }</code> mini-tables, where the resource is the name of the construction material, for example, "Naval Gun"
	\|-		\|-
	\| ~~description~~ \|\| ~~string~~ \|\| ~~The English~~-~~language flavour text~~ of the ~~ship~~		\| <code>crew_types</code> \|\| array of <code>ShipCrewAmount</code> \|\| pairs of <code>{ type, qty }</code> mini-tables, where the type is the name of the crew as spelled in-game, for example, "Crow's Eyes"
	\|-		\|-
	\| ~~construction_costs~~ \|\| array \|\| pairs of <code>{ ~~resource~~, qty }</code> mini-tables, where ~~the resource~~ is the name of the ~~construction material~~, for example, "~~Naval~~ Gun"		\| <code>stats_base</code> \|\| array of <code>ShipStatAmount</code> \|\| pairs of <code>{ stat, qty }</code> mini-tables, where stat is the name of the stat as spelled in-game, for example, "Gun Damage" or "Manoeuvrability"
	\|-		\|-
	\| ~~crew_types~~ \|\| ~~array~~ \|\| ~~pairs~~ of <code>{ ~~type~~, qty }</code> ~~mini-tables, where~~ the type ~~is the name of the crew as spelled in-game, for example, "Crow~~'~~s Eyes"~~		\| <code>stats_crew_bonuses</code> \|\| map of arrays of <code>ShipStatAmount</code> \|\| by crew_type's <code>type</code>, each returns an array of <code>{ stat, qty }</code> like <code>stats_base</code> but showing the marginal bonus '''per additional individual crew member of that type'''
	\|-		\|-
	\| ~~stats_base~~ \|\| array ~~\|\| pairs~~ of <code>~~{ stat, qty }~~</code> ~~mini-tables, where stat is~~ the ~~name~~ of ~~the stat as spelled in-game~~, ~~for example, "Gun Damage" or "Manoeuvrability"~~		\| <code>stats_max</code> \|\| array of <code>ShipStatAmount</code> \|\| calculated table of the maximum stats with the most number of advanced crew, similar structure to <code>stats_base</code>
	\|-		\|-
	\| ~~stats_crew_bonuses~~ \|\| ~~map \|\| by crew_type's~~ <code>~~type~~</code>~~, each returns an array~~ of <code>{ ~~stat~~, qty }</code> ~~like~~ <code>~~stats_base~~</code> ~~but showing the marginal bonus '''per additional individual crew member of that type'''~~		\| <code>unlock_points</code> \|\| array of <code>ShipUnlockAmount</code> \|\| calculated pairs of <code>{ path, qty }</code> mini-tables based on the ship's <code>principle_path</code> and <code>hybrid_path</code>
	\|}		\|}

Line 81:		Line 113:
	Construction, crew, and stats use ordered arrays of pairs of data: The first field is a resource's, crew type's , or stat's name, as spelled in-game, and the second field is the quantity.		Construction, crew, and stats use ordered arrays of pairs of data: The first field is a resource's, crew type's , or stat's name, as spelled in-game, and the second field is the quantity.

	* <code>ship.construction_costs</code> is an array of <code>resource–qty</code> pairs.		* <code>ship.construction_costs</code> is an array of <code>ShipResourceAmount</code>, <code>resource–qty</code> pairs.
	* <code>ship.crew_types</code> is an array of <code>type–qty</code> pairs.		* <code>ship.crew_types</code> is an array of <code>ShipCrewAmount</code>, <code>type–qty</code> pairs.
	* <code>ship.stats_base</code> is an array of <code>stat–qty</code> pairs.		* <code>ship.stats_base</code> is an array of <code>ShipStatAmount</code>, <code>stat–qty</code> pairs.
	* <code>ship.stats_crew_bonuses</code> is several arrays of <code>stat–qty</code> pairs.		* <code>ship.stats_crew_bonuses</code> is several arrays of <code>ShipStatAmount</code>, <code>stat–qty</code> pairs.
			* <code>ship.stats_max</code> is an array of <code>ShipStatAmount</code>, <code>stat-qty</code> pairs.
			* <code>ship.unlock_points</code> is an array of <code>ShipUnlockAmount</code>, <code>path-qty</code> pairs.

	==== Crew bonuses ====		==== Crew bonuses ====
Line 91:		Line 125:

	<pre>local bonuses = ship.stats_crew_bonuses["Scallywags"]</pre>		<pre>local bonuses = ship.stats_crew_bonuses["Scallywags"]</pre>

			To get the highest possible maximum stats, use <code>ship.stats_max</code> instead, which is pre-calculated.

76561197969631737: 76561197969631737 moved page Module:Ship data.lua/doc to Module:Ships data/doc without leaving a redirect: Misspelled title: Pluralized to match intent. Removed filename extension from Module name

2026-08-07T18:14:28Z

76561197969631737 moved page Module:Ship data.lua/doc to Module:Ships data/doc without leaving a redirect: Misspelled title: Pluralized to match intent. Removed filename extension from Module name

← Older revision		Revision as of 18:14, 7 August 2026
(No difference)

76561197969631737: Added doc page for ships_data

2026-08-06T02:19:18Z

Added doc page for ships_data

New page

Ship data for ''Corsair Cove'': 29 ships, schema validated at load time.

Use from other modules and templates via <code>#invoke</code> or <code>require</code>:

<pre>local ships_data = require("Module:Ships_data")</pre>

== Functions ==

'''Important: Do not mutate returned tables.''' To save performance, the tables are '''not''' copied first. Modifications to the returned values will contaminate other uses of those tables.

=== get_ship_by_name ===

Returns one ship record, or <code>nil</code> if the name isn't found.

<pre>local ship = ships_data.get_ship_by_name("Landlubber")</pre>

Name must match exactly, including spaces, for example <code>"Iron Fist"</code>.

=== get_ship_by_index ===

Returns the ship record at that position in canonical order, or <code>nil</code> if out of range. Canonical order is from Tier 1 to 6, clockwise starting from the top around the Compass.

<pre>local ship = ships_data.get_ship_by_index(1)</pre>

=== get_all_ships ===

Returns the full array of ship records, in canonical order. Canonical order is from Tier 1 to 6, clockwise starting from the top around the Compass.

<pre>for i, ship in ipairs(ships_data.get_all_ships()) do
...
end</pre>

=== get_count_of_ships ===

Returns the number of ships.

<pre>for i = 1, ships_data.get_count_of_ships() do
local ship = ships_data.get_ship_by_index(i)
end</pre>

=== get_ship_class_description ===

Flavour text for the class of ship, aligned with the Principle Paths. Pass in the <code>class</code> or <code>hybrid_class</code> field from a ship record to get its description. (The method ignores any trailing plus signs for the hybrid ships. Returns <code>nil</code> for unknown classes.

<pre>local flavour_text = ships_data.get_ship_class_description("Destroyer+")</pre>

== Ship record shape ==

Each record in ships_data is a table with the following fields:

{|class=wikitable
! Field !! Type !! Note
|-
| name || string || Display name
|-
| tier || number || 1..6, inclusive
|-
| principle_path || string || Primary Principle Path alignment of the class of ship
|-
| class || string || Primary class of the ship, with an trailing plus sign for hybrids, similar to their in-game display, for example "Notoriety"
|-
| hybrid_path || string || Secondary Principle Path alignment of the class of ship, according to the unlock requirement on the Compass (never has a trailing plus sign)
|-
| icon_filename || string || The filename, including the extension, of the image of the ship, for example, <code>"T_Ship_Starter.png"</code>
|-
| pier || string || The pier required to build the ship, for example, "Shallow Pier"
|-
| description || string || The English-language flavour text of the ship
|-
| construction_costs || array || pairs of <code>{ resource, qty }</code> mini-tables, where the resource is the name of the construction material, for example, "Naval Gun"
|-
| crew_types || array || pairs of <code>{ type, qty }</code> mini-tables, where the type is the name of the crew as spelled in-game, for example, "Crow's Eyes"
|-
| stats_base || array || pairs of <code>{ stat, qty }</code> mini-tables, where stat is the name of the stat as spelled in-game, for example, "Gun Damage" or "Manoeuvrability"
|-
| stats_crew_bonuses || map || by crew_type's <code>type</code>, each returns an array of <code>{ stat, qty }</code> like <code>stats_base</code> but showing the marginal bonus '''per additional individual crew member of that type'''
|}

=== Nested pairs ===

Construction, crew, and stats use ordered arrays of pairs of data: The first field is a resource's, crew type's , or stat's name, as spelled in-game, and the second field is the quantity.

* <code>ship.construction_costs</code> is an array of <code>resource–qty</code> pairs.
* <code>ship.crew_types</code> is an array of <code>type–qty</code> pairs.
* <code>ship.stats_base</code> is an array of <code>stat–qty</code> pairs.
* <code>ship.stats_crew_bonuses</code> is several arrays of <code>stat–qty</code> pairs.

==== Crew bonuses ====

The bonuses are first keyed by the crew type's name. Keys match that ship's <code>crew_types</code> types. Typed in the table are fractional values of what is shown in-game divided by the number of crew. This means when working with this data, each individual value in the <code>stat–qty</code> pair is the marginal additional stat that '''one crew member''' contributes to the ship.

<pre>local bonuses = ship.stats_crew_bonuses["Scallywags"]</pre>