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.

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. To avoid any issues, use [https://notepad-plus-plus.org/download/v7.5.6.html Notepad++] and check the encoding in the bottom right.

==Header==
Each file starts with a simple block titled <code>CaveInfo</code>. It contains only one parameter, <code>{c000}</code>, which takes two values, a <code>4</code> and 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. After this comes a series of blocks, with each group of 5 belonging to a sublevel.

==Sublevel==
Each sublevel starts with a block commented with <code>FloorInfo</code>, where the sublevel's data is, and then four blocks that determine what objects to spawn. The process is explained in the sections for these blocks, but the general algorithm is also explained '''[[Cave spawning|here]]'''.

The comment for the first sublevel's <code>FloorInfo</code> block has a number to the left of it; this is the [[#Header|total number of sublevels]]).

===Object categories===
Before you continue, it is important to know that objects can belong to one of five categories:

# '''"Main"'''
#* Are defined in [[#TekiInfo|TekiInfo]].
#* Are not treasures.
#* Are not gates.
#* Appear inside "room" units.
#* Their "[[#Type|type]]" is not "6".
# '''"Decorative"'''
#* Same rules as the "main" category, except...
#* Their "[[#Type|type]]" is "6".
# '''Dead end'''
#* Are defined in [[#CapInfo|CapInfo]].
#* Are not gates.
#* Appear inside "dead end" units.
# '''Treasure'''
#* Are defined in [[#ItemInfo|ItemInfo]].
#* Are exclusively treasures.
# '''Gate'''
#* Are defined in [[#GateInfo|GateInfo]].
#* Are exclusively gates.

These category names are not laws, just 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 objects in different categories differently, and also controls them differently.

===FloorInfo===
This block has a large number of parameters that determine how the sublevel works. All content in these parameters consist of two words. The first word is a number, <code>4</code> for numbers and <code>-1</code> for strings. The second word is the actual value of the parameter - the one you can modify.

{{todo|Figure out what happens if you change {f000} and {f001}.}}

{| 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" [[#Object categories|category]]. See [[#Amount]] for more details. If this is set to 0, absolutely no objects of the "main" category will spawn. || 敵最大数
|-
| <code>{f003}</code> || Ideal maximum number of objects in the treasure [[#Object categories|category]]. || アイテム最大数
|-
| <code>{f004}</code> || Ideal maximum number of objects in the gate [[#Object categories|category]]. || ゲート最大数
|-
| <code>{f005}</code> || Number of "room" cave units. || ルーム数
|-
| <code>{f006}</code> || Ratio that controls how many corridors there are compared to 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> || Maximum number of dead ends. || キャップ最大数
|-
| <code>{f015}</code> || 1 is normal, 0 will ignore all dead end spawns ([[#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 [[#Object categories|"main"]] objects and the [[#Object categories|"decorative"]] objects to spawn on the sublevel.

The first number in the block is the total of entries. It is commented with <code>num</code>. Each entry consists of two lines. The first line in an entry determines how it spawns, the object's class, what treasure it has inside, how many to spawn, and/or how likely this object is to be used to fill the free "main" object slots. The second line of each entry is the "type" of the object.

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

====Class====
The first word in the first line of each entry contains the object class (fire geyser, Red Bulborb, clover, etc.), using its internal name (case insensitive). Treasures will not work; use the [[#ItemInfo|<code>ItemInfo</code> block]] for that.

If it is an enemy and is carrying something inside it, the internal name of that object's class is also included in that word, in lowercase, after an underscore (e.g. <code>Chappy_key</code> for a Red Bulborb carrying The Key). In this case, the name of the enemy itself is no longer case insensitive and must be written in CamelCase, although exact casing depends on the object. Note that an underscore isn't a sure-fire way to know 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.

====Spawn method====
Some objects spawn from the sky, 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 name of the object, without a space in between. Example: <code>$4BombOtakara</code>. 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
|-
| <code>$</code> || Always fall 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> || Only fall if a Pikmin is nearby, leaders are ignored. || 
|-
| <code>$3</code> || Only fall if a leader is nearby, Pikmin are ignored. || '''Unused'''.
|-
| <code>$4</code> || Only fall if Pikmin are carrying nearby. || 
|-
| <code>$5</code> || Only fall if a Purple causes an earthquake nearby. || 
|}

Not all objects support this feature. The objects that don't support the feature completely ignore the $ sign and spawn normally. No bosses or plants (besides Candypop Buds) are changed.

Here is a list of all other known objects and whether or not they are capable of using this behavior.

{| class="wikitable sortable"
! Enemy || Supported || Notes
|-
| Anode Beetle || Yes || 
|-
| Anode Dweevil || Yes ||
|-
| Antenna Beetle || No ||
|-
| Armored Cannon Beetle Larva (Buried) || No ||
|-
| Armored Cannon Beetle Larva (Free) || Yes || 
|-
| Bomb-rock || Yes ||
|-
| Breadbug || No ||
|-
| Bulbmin || Yes ||
|-
| Bulborb Larva || Yes || Uses a unique falling animation, the same animation thats used when they are born from the Empress Bulblax.
|-
| Bumbling Snitchbug || Yes || Floats down from the sky.
|-
| Careening Dirigibug || Yes || Floats down from the sky.
|-
| Caustic Dweevil || Yes || 
|-
| Cloaking Burrow-nit || No || 
|-
| Creeping Chrysanthemum || No || 
|-
| Crimson Candypop Bud || Yes || 
|-
| Decorated Cannon Beetle || Yes || 
|-
| Doodlebug || No || 
|-
| Dwarf Bulbear || Yes || 
|-
| Dwarf Orange Bulborb || Yes || 
|-
| Dwarf Red Bulborb || Yes || 
|-
| Egg || Yes  || Breaks upon hitting the ground.
|-
| Electrical Wire || No || 
|-
| Falling Boulder || Yes || 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.
|-
| Female Sheargrub || No  || 
|-
| Fiery Blowhog || Yes  || 
|-
| Fiery Bulblax || Yes  || 
|-
| Fiery Dweevil || Yes  || 
|-
| Fire Geyser || No  || 
|-
| Foxtail || No  || 
|-
| Gas Pipe || No  || 
|-
| Gatling Groink (Both variants) || Yes  || 
|-
| Golden Candypop Bud || Yes  || 
|-
| Greater Spotted Jellyfloat || Yes  || Floats down from the sky.
|-
| Hairy Bulborb || Yes  || 
|-
| Hermit Crawmad || No || 
|-
| Honeywisp || No  || 
|-
| Iridescent Flint Beetle || No  || 
|-
| Iridescent Glint Beetle || No  || 
|-
| Ivory Candypop Bud || Yes  || 
|-
| Lapis Lazuli Candypop Bud || Yes  || 
|-
| Lesser Spotted Jellyfloat || Yes  || Floats down from the sky
|-
| Lithopod Boulder (Unused) || Yes  || The trail particles of the boulder will remain stationary in the air until the rolling boulder is triggered by the player.
|-
| Male Sheargrub || No  || 
|-
| Mamuta || No  || 
|-
| Mitite || No  || 
|-
| Munge Dweevil || Yes  || 
|-
| Orange Bulborb || Yes  || 
|-
| Puffy Blowhog || Yes  || Floats down from the sky.
|-
| Queen Candypop Bud || Yes  || 
|-
| Ravenous Whiskerpillar || No  || 
|-
| Red Bulborb || Yes  || 
|-
| Shearwig || No  || 
|-
| Skitter Leaf || No  || 
|-
| Snow Bulborb || Yes  || 
|-
| Spotty Bulbear || Yes  || 
|-
| Swooping Snitchbug || Yes  || Floats down from the sky.
|-
| Toady Bloyster || No  || 
|-
| Unmarked Spectralids || No  || 
|-
| Violet Candypop Bud || Yes  || 
|-
| Volatile Dweevil || Yes  || 
|-
| Water Dumple || Yes  || 
|-
| Waterwraith Rollers (Unused) || No  || 
|-
| Watery Blowhog || Yes  || 
|-
| Withering Blowhog || Yes  || Floats down from the sky.
|-
| Wogpole || Yes  || 
|-
| Wollywog || Yes  || 
|-
| Yellow Wollywog || Yes  || 
|}

====Amount====
====="Main" category objects=====
The second word in the first line of each entry is a number, where the last digit is the [[Cave spawning#Weighted distribution|filler distribution weight]] and the other digits are the minimum amount to spawn. This line is commented with <code>weight</code>. If there is only one digit, it indicates the filler distribution weight, and the minimum amount is set to 0.

The game will spawn the enemies requested in the "minimum amount" fields (provided there is enough physical space in the sublevel). After the game is done spawning all of these, provided that the enemy total isn't equal to or over <code>{f002}</code> yet, it will then try to fill in the remaining slots with any enemies that have a non-zero filler distribution weight, as explained [[Cave spawning#Weighted distribution|here]]. If there are no enemies to pick for the filler distribution, then the game simply doesn't spawn any fillers.

Note that when trying to spawn an enemy, if there are no more vacant slots of the specified type, the game will not spawn that enemy, but will still add 1 to the counter of enemies currently in the sublevel. This means that if you have a cave with just one room, that has 4 spawn locations for type 0 and 4 for type 1, you specify 10 as the maximum of enemies ({f002}), and specify 8 Wogpoles of type 0, and then a Dwarf Red Bulborb with a filler distribution weight and type 1, the game will try to spawn the 8 mandatory Wogpoles, only spawn 4 because there are no more vacant slots, and will still count the other 4 as if they exist. This means it will only pick 2 Dwarf Red Bulborbs to reach the maximum in {f002}.

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

====="Decorative" category objects=====
The second word in the first line of each entry is a number, which indicates the exact number of objects of that type to spawn. There are no limits to the number of objects of this type to spawn, except for the amount of spawning locations available in the sublevel's generated layout, and there is no random distribution either.

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

====Type====
This number controls what type of object this is (more or less), and where it spawns. The number ranges from 0 to 8, and most 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.

The type is defined in the second line of each entry, and is commented with <code>type</code>. 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. Also note that objects in some categories cannot use some numbers, and that objects in the treasure and gate categories cannot specify a type.

{| class="wikitable"
! rowspan="2" | Group || rowspan="2" | Content || rowspan="2" | <code>layout.txt</code> comment || rowspan="2" | Notes || colspan="4" | Category availability
|-
! "Main" || "Decorative" || Dead end
|-
| 0 || Enemy Group A || <code>Teki A</code> || || style="background-color: #aca;" | Yes || style="background-color: #caa;" | No || style="background-color: #aca;" | Yes
|-
| 1 || Enemy Group B || <code>Teki B</code> || || style="background-color: #aca;" | Yes || style="background-color: #caa;" | No || style="background-color: #aca;" | Yes
|-
| 2 || Treasure || <code>Item</code> || Not used by any object in the canon game. In a cave unit, it marks the location of objects defined in [[#CapInfo|CapInfo]]. || style="background-color: #caa;" | No || style="background-color: #caa;" | No || style="background-color: #aca;" | Yes
|-
| 3 || {{unsure|Unknown}} || || There is no object or cave unit that uses this number. || style="background-color: #caa;" | No || 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 hole/geyser in a room, if dead ends are not present in the sublevel. || style="background-color: #caa;" | No || 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 connecting cave units. || style="background-color: #aca;" | Yes || style="background-color: #caa;" | No || style="background-color: #aca;" | Yes
|-
| 6 || Plant || <code>Plant</code> || Commonly used by decorative plants. || style="background-color: #aca;" | Yes || style="background-color: #aca;" | Yes || 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 || style="background-color: #caa;" | No
|-
| 8 || Enemy Group C || <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 || style="background-color: #aca;" | Yes
|}

===== Example =====
<pre>
	{f002} 4 5 	# 敵最大数

(...)

# TekiInfo
{
	2 	# num
	$Tadpole 23 	# weight
	0 	# type
	Sokkuri_bane 9 	# weight
	1 	# type
}
</pre>

Assuming there's enough space in the sublevel, this would make the game spawn 2 Wogpoles, that only pop up from the sky when you get close. Then, it spawns 3 randomly picked enemies, with each enemy having a 3/12 chance of being a Wogpole (like the aforementioned ones, these spawn from the sky), and a 9/12 chance of being a Skitter Leaf that is carrying a Coiled Launcher. Any Wogpole in this sublevel will spawn in the set of coordinates that belong to group 0, whereas any Skitter Leaf will spawn on the coordinates of group 1.

===ItemInfo===
The next block is titled <code>ItemInfo</code>. It controls how treasures spawn. Treasures inside enemies aren't included here, but are instead defined in [[#TekiInfo|TekiInfo]] or [[#CapInfo|CapInfo]]'s objects.

The first number in the block is the total of entries. It is titled <code>num</code>. Each entry consists of one line. This line contains the internal name of the treasure, in all lowercase, and then after a space, the amount to spawn. This amount uses the same scheme as the [[#Amount|<code>TekiInfo</code> block]], except when deciding the random spawn distribution, the limit is decided by <code>{f003}</code> instead. If you try to spawn something here that is not a treasure, the game will crash.

====Example====
<pre>
	{f003} 4 4

(...)

# ItemInfo
{
	3
	key 10
	gold_medal 12
	saru_head 04
}
</pre>

The game will spawn one ''The Key'' and one ''Lustrous Element'', the next two treasures (because <code>{f003}</code> is set to <code>4</code>), will have a 2/6 chance of being a ''Lustrous Element'', and a 4/6 chance of being a ''Colossal Fossil''.

===GateInfo===
<code>GateInfo</code> controls what gates will appear. Each individual gate on a sublevel is randomly colored. The game will spawn the number of gates defined in <code>{f004}</code>, but will stop spawning them if there isn't enough room.

The first number in the block is the total of entries. It is titled <code>num</code>.
# Each entry consists of two lines.
# The first line is the gate's HP. It is titled with <code>life</code>. 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>).
# The second line is the [[Cave spawning#Weighted distribution|spawn distribution weight]]. {{unsure|Only the last digit of this number is used.}} If the number is 0, this type of gate will not spawn at all, of course.

====Example====
<pre>

	{f004} 4 2

(...)

# GateInfo
{
	2
	gate 4000.000000
	1
	gate 2500.000000
	1
}
</pre>

This will spawn two different types of gates of random colours in random locations. The total number of gates appearing in the level is dependent on the value set in <code>{f004}</code>, which in this case is <code>2</code> so only two gates will spawn.

===CapInfo===
<code>CapInfo</code> determines what objects to spawn in dead ends.

The first number in the block is the total number of entries. It is titled <code>num</code>. Each entry consists of three lines.

The logic is the exact same as spawning objects in the [[#TekiInfo|<code>TekiInfo</code> block]], except for the following things:
# Each entry is defined by three lines. There is an extra line before the usual <code>weight</code> and <code>type</code> lines, which determines, presumably, the type of dead end this spawn applies to. It is titled <code>captype</code>, and always has the value <code>0</code>.
# Objects spawned here appear in dead ends, not in the locations determined by the "type".
# Enemies spawned with this block do not count for any limit (e.g. <code>{f002}</code>).
# Treasures can also be specified here.

====Example====
<pre>
# CapInfo
{
	2
	0
	$2Egg 10
	1
	0
	WhitePom 10
	1
}
</pre>

This will spawn an egg that will fall down when a Pikmin gets close, and a Ivory Candypop Bud, both in random dead-ends.

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