Editing Cave generation parameters

In ''Pikmin 2'', the files that define a cave's settings can be found in <code>/user/Mukki/mapunits/caveinfo</code>. For instance, the Emergence Cave uses <code>tutorial_1.txt</code>. All comments (Japanese or English statements followed by a <code>#</code>) are unnecessary and deleting them will save file space.

To avoid any issues when reading or writing these files, use [https://notepad-plus-plus.org/download/v7.5.6.html Notepad++].

== Concepts ==
It is important to know these basic concepts.

Each object-related block in a sublevel has a series of data on what objects to spawn, and how. In this page, each of these data is called an '''entry'''. Each entry merely contains information about ''how'' to spawn an object, it does not actually reflect a specific object. For instance, there could be an entry for a Dwarf Bulborb that fall from the sky carrying the Essence of Desire, but the game could spawn 10 Dwarf Bulborbs from this entry &ndash; in this case all ten would fall from the sky and carry the Essence of Desire.

Each entry can belong to one of the following categories, which affect many things, some of which are detailed in this table:

{| class="wikitable sortable"
! Category || Block || Kind of object || Locations || Min. amount? || Used for filler? || Other notes
|-
! Main
| [[#TekiInfo|TekiInfo]]
| Anything but treasures and gates
| "Room" cave units
| Yes
| Until the limit in [[#FloorInfo|parameter <code>{f002}</code>]]
| [[#Spawn type|Spawn type]] is 0, 1, 5, or 8
|-
! Decorative
| [[#TekiInfo|TekiInfo]]
| Anything but treasures and gates
| "Room" cave units
| Yes
| No
| [[#Spawn type|Spawn type]] is 6
|-
! Treasure
| [[#ItemInfo|ItemInfo]]
| Treasures only
| "Room" cave units or those with "item" in the name
| Yes
| Until the limit in [[#FloorInfo|parameter <code>{f003}</code>]]
| 
|-
! Gate
| [[#GateInfo|GateInfo]]
| Gates only
| Seams between units
| No
| Until the limit in [[#FloorInfo|parameter <code>{f004}</code>]]
|-
! Dead end
| [[#CapInfo|CapInfo]]
| Anything but gates
| "Dead end" cave units with "item" in the name
| Yes
| Until it runs out of dead ends
| 
|}

These categories are not recognized by the game, and their names are merely guidelines. This is because you can have fully-functional enemies in the "decorative" category, and you can have cosmetic plants in the "main" category, for instance. What is important is understanding that the game reads and controls object entries differently depending on a lot of factors, and this categorization is just a simple way of explaining everything.

While this page explains how the text file works, it will not explain how spawning works. For that, there is the '''[[cave spawning]]''' article. You don't need to read the whole thing, but for context for this article, you should at least read the [[Cave spawning#Summary|summary]].

== Format ==
These text files must be encoded in Shift-JIS, or at least ASCII. If the file is saved as a UTF-8 text file with the <code>EF BB BF</code> magic word at the start, the game will not read it correctly, assuming you only have one sublevel. With Notepad++, you can check if the encoding is right in the bottom right.

Each file starts with the header, [[#CaveInfo|CaveInfo]]. Afterwards comes the data for each sublevel. Each sublevel consists of five consecutive blocks of information: [[#FloorInfo|FloorInfo]], [[#TekiInfo|TekiInfo]], [[#ItemInfo|ItemInfo]], [[#GateInfo|GateInfo]], and [[#CapInfo|CapInfo]].

When this page refers to "parameters", it means something along the lines of <code>{f000} 4 0</code>. The first word is the parameter's name. The second word is the type: <code>4</code> for numbers and <code>-1</code> for strings. The third word is the parameter's value &ndash; the one you can modify.

=== CaveInfo ===
The header block is usually commented with <code>CaveInfo</code>. It contains only one parameter, <code>{c000}</code>, which controls the number of sublevels in the cave.

After the opening block there is a lone number. This number is, once again, the number of sublevels in the cave.

=== FloorInfo ===
Each sublevel starts with a block typically commented with <code>FloorInfo</code>. It has a large number of parameters that determine how the sublevel works. The following table lists what parameters exist, what they do, and what comments (in Japanese) usually follow the value.

{{todo|Figure out what happens if you change {f000} and {f001}. Also specify what happens if {f003}/{f004} are set to 0.}}

{| class="wikitable sortable"
|-
! Parameter || Description || Japanese comment
|-
| <code>{f000}</code> || The sublevel number this sublevel belongs to, minus 1. For example, if this floor is sublevel 1, the value is 0. Comment translates to "floor introduction". Seems to crash the game if lower than the current sublevel. || 階はじめ
|-
| <code>{f001}</code> || Same as above. Comment translates to "floor end". Seems to duplicate the floor and replace future sublevels. For example, if you are on sublevel 1 ({f000} is set to 0) when {f001} is set to 2, sublevels 2 and 3 will be the exact same as the first sublevel. The other sublevels will be untouched.  || 階おわり
|-
| <code>{f002}</code> || Ideal maximum number of objects in the main [[#Concepts|category]]. See [[#Amount|here]] and [[#Weight|here]] for more details. If this is set to 0, absolutely no objects of the main category will spawn. || 敵最大数
|-
| <code>{f003}</code> || Same as <code>{f002}</code> but for objects in the treasure [[#Concepts|category]]. It does not count treasures inside enemies. || アイテム最大数
|-
| <code>{f004}</code> || Same as <code>{f002}</code> but for objects in the gate [[#Concepts|category]]. || ゲート最大数
|-
| <code>{f005}</code> || Number of "room" cave units. || ルーム数
|-
| <code>{f006}</code> || Corridor probability. If this number is higher, the game will spawn more corridors relative to the number of rooms. || ルートの割合
|-
| <code>{f007}</code> || 1 if this floor has a geyser, 0 otherwise. || 帰還噴水(1=あり)
|-
| <code>{f008}</code> || [[Cave unit definition file]] name. || 使用ユニット
|-
| <code>{f009}</code> || Lighting definition file name. || 使用ライト
|-
| <code>{f00A}</code> || Skybox. Valid values are: <code>none</code>, <code>f010</code>, <code>vrbox</code> (they all mean none), <code>ice</code> (ice cavern), <code>test</code> (cavern), <code>build</code> (steel), <code>hiroba</code> (garden), <code>flooring</code> (wooden floor), <code>tatami</code> (carpet). || VRBOX
|-
| <code>{f010}</code> || 1 if the next sublevel hole is clogged, 0 otherwise. || 階段を壊す岩で隠す(0=オフ 1=オン)
|-
| <code>{f011}</code> || Ambient effect; 0 for unknown effect typically used in soil/remaining themes, 1 for echo normally used for metal, 2 for low long sound that fades in and out typically used for concrete, 3 for unknown effect typically used for tile, 4 for unknown effect typically used for garden, 5 for {{unknown|no effect}} typically used for toy. || α属性
|-
| <code>{f012}</code> || Music type; 0 for normal, 1 to mute (until a boss), 2 to use rest sublevel music || β属性
|-
| <code>{f013}</code> || 1 if sublevel has an invisible solid plane of ground, generally used for the <code>hiroba</code>, <code>flooring</code> and <code>tatami</code> skyboxes. If 0, Pikmin can fall off the edge to their deaths. || 隠し床
|-
| <code>{f014}</code> || Dead end probability (0-100). E.g. if this value is 50, open doors will be set to dead ends with 50% probability. || キャップ最大数
|-
| <code>{f015}</code> || File format version; 1 is normal, 0 will ignore all dead end spawns ([[#CapInfo|CapInfo]]) || Version
|-
| <code>{f016}</code> || {{unsure|Time until the Waterwraith appears. || BlackManTimer
|-
| <code>{f017}</code> || 0 is normal, anything else makes it spawn two (connected) seesaw blocks randomly in the level. May spawn the leaders and Pikmin inside one. '''Unused.''' || 沈む壁
|}

=== TekiInfo ===
<code>TekiInfo</code> determines the [[#Concepts|main category]] objects and the [[#Concepts|decorative category]] objects to spawn on the sublevel. It also controls what sort of spawn points they appear in, if they fall from the sky or not, if they are carrying a treasure inside, and more. Gates and treasures cannot be specified here (other than the treasures that are [[#Carrying|carried]] by enemies). The game will spawn the minimum amounts specified in these entries and then, in the case of main category objects, keep filling randomly until the limit in [[#FloorInfo|parameter <code>{f002}</code>]]. These objects only appear in "room" cave units.

The first number in the block is the total of [[#Entry|entries]]. It is usually commented with <code>num</code>. Each entry consists of two lines:

# The first line in an entry starts with the object's [[#Fall method|fall method]], the object's [[#Class|class]], what treasure it is [[#Carrying|carrying]], then a space, then the [[#Amount|amount]] to spawn, and/or its [[#Weight|random filling weight]]. Note that entries of the decorative category do not have a random filling weight. It is typically commented with the word "weight".
# The second line of each entry is the [[#Spawn type|spawn type]]. It is typically commented with the word "type".

=== ItemInfo ===
<code>ItemInfo</code> controls what [[#Concepts|treasure category]] objects spawn. The game will spawn the minimum amounts for these treasures, and then will keep filling randomly until it reaches the limit defined in [[#FloorInfo|parameter <code>{f003}</code>]]. Treasures inside enemies aren't included here, nor are they counted for the limit. Instead, they are defined in the [[#Carrying|carrying]] data of objects in [[#TekiInfo|TekiInfo]] or [[#CapInfo|CapInfo]]. Only treasures can be specified in this block &ndash; if you try to spawn something here that is not a treasure, the game will crash. These objects only appear in "room" cave units, or any unit that has "item" in the name.

The first number in the block is the total of [[#Entry|entries]]. It is usually commented with <code>num</code>. Each entry consists of one line:

# This line contains the object's [[#Class|class]], then a space, then the [[#Amount|amount]] to spawn, and/or its [[#Weight|random filling weight]]. It is typically commented with the word "weight". 

=== GateInfo ===
{{todo|Confirm the claim that the weight only uses the last digit.}}
<code>GateInfo</code> controls what [[#Concepts|gate category]] objects will appear. Each individual gate on a sublevel is randomly colored, and always appears in seams. The game will spawn the number of gates defined in [[#FloorInfo|parameter <code>{f004}</code>]]. These objects appear in the seams between two cave units.

The first number in the block is the total of [[#Entry|entries]]. It is usually commented with <code>num</code>. Each entry consists of two lines:

# The first line is the gate's HP. This line starts with any word (although the word <code>gate</code> is what's used in the vanilla game), and after a space, the amount of hit points it has, with decimal places (e.g. <code>1000.000000</code>). It is typically commented with the word "life".
# The second line contains the object's [[#Weight|random filling weight]]. Only the last digit is read by the game, though. If the weight number is 0, the game will not spawn any gate from this entry, of course. It is typically commented with the word "weight".

=== CapInfo ===
<code>CapInfo</code> determines what [[#Concepts|dead end category]] objects to spawn. It works similarly to the [[#TekiInfo|<code>TekiInfo</code> block]], though with some differences:
* While in the <code>TekiInfo</code> block the locations of objects spawned is determined by the spawn type, that is not the case here. These objects only spawn in "dead end" cave units with "item" in the name.
* Objects spawned with this block do not count for any limit (e.g. [[#FloorInfo|parameter <code>{f003}</code>]]).
* Treasures can also be specified in this block.

The first number in the block is the total of [[#Entry|entries]]. It is usually commented with <code>num</code>. Each entry consists of three lines:

# The first line is presumably, the type of dead end this spawn applies to. It always has the value <code>0</code> in the vanilla game. It is typically commented with the word "captype".
# The second line in an entry starts with the object's [[#Fall method|fall method]], the object's [[#Class|class]], what treasure it is [[#Carrying|carrying]], then a space, then the [[#Amount|amount]] to spawn, and/or its [[#Weight|random filling weight]]. It is typically commented with the word "weight".
# The third line of each entry is the "type". 0 makes it so two objects spawn in the same spot, while 1 allows only one object. It is typically commented with the word "type".

== Entry ==
Depending on its [[#Concepts|category]], an entry can have or not have certain information.

To note is that if something is wrong with the entry's data, the game will probably break down when trying to spawn an item of said entry, but it might also trigger an error handler. If it does, the object will be turned into a fully-functional Common Glowcap. Typing an invalid class name will trigger the error handler.

=== Class ===
[[#Concepts|Categories]]: main, decorative, treasure, dead end.

This is the class of object to spawn (e.g. fire geyser, Red Bulborb, clover, etc.). The name typed here must match the [[Pikmin 2 identifiers|internal name]]. (e.g. <code>MaroFrog</code> for a Wollywog.) For main, decorative, and dead end category objects, this name is normally not case-sensitive, but if it's an enemy [[#Carrying|carrying]] something, then it becomes case-sensitive. For treasure category objects, the name must be all lowercase.

=== Carrying ===
[[#Concepts|Categories]]: main, decorative, dead end.

An entry can specify if an enemy is meant to carry a treasure inside it. If it is, then after the [[#Class|class]] name there should be an underscore, and then afterwards, in all lowercase, the [[Pikmin 2 identifiers|internal name]] of said treasure. (e.g. <code>Chappy_key</code> for a Red Bulborb carrying The Key.) Note that for entries regarding enemies that are carrying something, the class name becomes case-sensitive.

Note that just because an underscore exists doesn't mean for sure that one object is carrying another. If the game sees the name <code>Wakame_s</code>, it isn't going to think that it's an object <code>Wakame</code> carrying an object <code>s</code>, but rather that it is a small shoot. Also note that treasures specified here do not count towards the limit in [[#FloorInfo|parameter <code>{f003}</code>]].

=== Fall method ===
[[#Concepts|Categories]]: main, decorative, dead end.

Some objects spawn in the sky and then fall, like Volatile Dweevils that only appear when you get close to their spawn position. To get an object to do this, write a dollar sign and/or a number, before the [[#Class|class]] of the entry, without a space in between. (e.g. <code>$4BombOtakara</code> for a Volatile Dweevil that spawns when Pikmin are carrying nearby). You have to write a specific thing to get a specific behavior, and if you write an invalid one, the game crashes:

{| class="wikitable sortable"
! Code || Effect || Notes
|-
| (Nothing) || Spawns normally. || 
|-
| <code>$</code> || Falls, if a Pikmin or leader is nearby. || 
|-
| <code>$0</code> || Triggers the Common Glowcap error handler. || '''Unused'''.
|-
| <code>$1</code> || Identical to <code>$</code>. || 
|-
| <code>$2</code> || Falls, if a Pikmin is nearby. Leaders are ignored. || 
|-
| <code>$3</code> || Falls, if a leader is nearby. Pikmin are ignored. || '''Unused'''.
|-
| <code>$4</code> || Falls, if Pikmin are carrying nearby. || 
|-
| <code>$5</code> || Falls, if a Purple Pikmin causes an earthquake nearby. || 
|}

Not all objects support this feature. The objects that don't support the feature completely ignore whatever fall method is written and spawn normally. Other objects support it, but have some interesting behavior. Here is a list of all possibilities:

{| class="wikitable mw-collapsible mw-collapsed"
! Objects || Result
|-
| 
* All bosses
* All plants (besides Candypop Buds)
* Antenna Beetle
* Armored Cannon Beetle Larva (buried version)
* Breadbug
* Cloaking Burrow-nit
* Creeping Chrysanthemum
* Doodlebug
* Electrical wire
* Female Sheargrub
* Fire geyser
* Gas pipe
* Hermit Crawmad
* Honeywisp
* Iridescent Flint Beetle
* Iridescent Glint Beetle
* Male Sheargrub
* Mamuta
* Mitite
* Ravenous Whiskerpillar
* Shearwig
* Skitter Leaf
* Toady Bloyster
* Unmarked Spectralids
* Waterwraith rollers (unused)
| Not supported
|-
| 
* Bumbling Snitchbug
* Careening Dirigibug
* Greater Spotted Jellyfloat
* Lesser Spotted Jellyfloat
* Puffy Blowhog
* Swooping Snitchbug
* Withering Blowhog
| Supported, floats down from the sky
|-
| 
* Bulborb Larva &ndash; Uses a unique falling animation, the same animation that's used when it is born from the Empress Bulblax.
* Egg &ndash; Breaks upon hitting the ground.
* Falling boulder &ndash; Falling boulders sort of float in place for a bit, then fall down at a much quicker speed than normal. If multiple boulders spawn inside of each other, they will bounce off of each other at an angle when they are triggered by the player.
* Lithopod boulder (unused) &ndash; The trail particles of the boulder will remain stationary in the air until the rolling boulder is triggered by the player.
| Supported, special behavior
|-
| 
* Everything else
| Supported, falls normally
|}

=== Amount ===
[[#Concepts|Categories]]: main, decorative, treasure, dead end.

Some entries can specify that the sublevel must spawn at least a minimum amount of objects from that entry. The game can possibly [[#Weight|spawn more randomly]] afterwards, but at least the minimum amount will be met (under ideal circumstances anyway). Note that while there are sublevel [[#FloorInfo|parameters]] that control the maximum number of main, treasure, or gate objects, they will not be taken into account when spawning these minimum amounts.

In an entry, the amount comes after the [[#Class|class]] (and [[#Carrying|carry]]), with a space in between. Whatever number is written here is the minimum amount. 0 can be used to specify that there is no minimum amount, and that this entry should only be used for random filler. The filler weight, described [[#Weight|here]], is another number that goes attached to this one. If the filler weight is present, then the amount number can be absent; in this case the game will assume it is 0. Note that while gate category entries need the minimum amount, the game will not actually do anything with that amount.

=== Weight ===
[[#Concepts|Categories]]: main, treasure, gate, dead end.

When the game wants to fill in the sublevel with some randomly-picked objects, it checks the relevant entries to figure out which ones it can pick, and with what chances, as detailed [[Cave spawning#Weighted distribution|here]]. It eventually stops spawning, and the exact conditions depend the [[#Concepts|category]] of the entry. Note that for many reasons, explained in the [[cave spawning]] article, objects may fail to appear, so the sublevel will contain fewer objects of a given category than the sublevel [[#FloorInfo|parameter]] for that limit specifies.

In an entry, the random filling weight comes directly after the [[#Amount|amount]], without even a space in between. The weight is only one digit, meaning it can only go from 0 to 9. If it is 0, the game will not use this entry for random filling. Note that if only one digit is present, then it refers to the weight, and the game assumes the minimum amount is 0. Also note that entries of the decorative category do not have weight.

{{credits|Jimble, [[User:Espyo|Espyo]]}}

=== Spawn type ===
[[#Concepts|Categories]]: main, decorative.

This number controls what type of spawning logic to use, where it spawns, and to a lesser degree, what category of object this is. The number ranges from 0 to 8, and most of these also correspond to a group of spawn coordinates. When spawning an instance of this object, the game picks a random coordinate from the group, if applicable. Note that certain entry categories can only use certain numbers.

The following table lists the possible numbers, and the comments on the various [[Cave unit definition file|unit layout files]] (in <code>/user/Mukki/mapunits/arc/*/texts.szs/layout.txt</code>) are also included due to them helping understand what each number means.

{| class="wikitable"
! rowspan="2" | Group || rowspan="2" | Content || rowspan="2" | <code>layout.txt</code> comment || rowspan="2" | Notes || colspan="2" | Category availability
|-
! Main || Decorative
|-
| 0 || "Easy" enemy group || <code>Teki A</code> || Commonly used for easier enemies. Objects using this spawn type can spawn multiple in the same spot. (Depends on the spawn point's minimum and maximum amount.) || style="background-color: #aca;" | Yes || style="background-color: #caa;" | No
|-
| 1 || "Hard" enemy group || <code>Teki B</code> || Commonly used for harder enemies. || style="background-color: #aca;" | Yes || style="background-color: #caa;" | No
|-
| 2 || Treasure || <code>Item</code> || Not used directly by any object in the vanilla game. In a cave unit, it marks the location of objects from the treasure category. || style="background-color: #caa;" | No || style="background-color: #caa;" | No
|-
| 3 || {{unsure|Unknown}} || || There is no object or cave unit that uses this number. || style="background-color: #caa;" | No || style="background-color: #caa;" | No
|-
| 4 || Hole/Geyser || <code>FixObj</code> || Objects can't use this number. In a cave unit, it marks a viable location for the next sublevel hole/geyser in a room, if dead ends are not present in the sublevel. || style="background-color: #caa;" | No || style="background-color: #caa;" | No
|-
| 5 || Seams || || Commonly used for hazards such as fire geysers, electrical wires and gas pipes. These spots are located in the seams between two connected cave units. || style="background-color: #aca;" | Yes || style="background-color: #caa;" | No
|-
| 6 || Plant || <code>Plant</code> || Commonly used by decorative plants. || style="background-color: #caa;" | No || style="background-color: #aca;" | Yes
|-
| 7 || Leader spawn || <code>Start</code> || Objects can't use this number. In a cave unit, it marks a possible player starting spot in the sublevel. The Y coordinate is ignored; it snaps to the ground. || style="background-color: #caa;" | No || style="background-color: #caa;" | No
|-
| 8 || "Special" enemy group || <code>Teki F</code> || Commonly used for boss locations, or the location of tower Gatling Groinks/buried Armored Cannon Beetle Larvae. Most rooms do not have coordinates for this. || style="background-color: #aca;" | Yes || style="background-color: #caa;" | No
|}

[[Category:Pikmin 2]]
[[Category:File formats]]