Map unit

Revision as of 10:43, 9 March 2022 by CEObrainz (talk | contribs) (→‎Rails)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Not to be confused with maps, stages or scenes.


Map units contain placement data for game maps (e.g. MainField/A-1). In other words, they are used to configure fixed object spawns on maps for actors such as scenery and enemies for example, in contrast to the AutoPlacement system, which dynamically spawns actors.


Types

Two types of map units exist: Static and Dynamic.

Static map units are loaded during stage generation (see GameScene for more details). Their name is suffixed with _Static. They can contain both map rails and map objects; furthermore objects can be linked to each other to implement custom game logic using the #Link system. Static units are always loaded in memory and will be visible if the player is within the actor's TraverseDist (draw distance) set in ActorInfo.product.sbyml. It's possible to see actors from the top-left to the bottom-right in open-world stages (MainField and AocField) if the TraverseDist is set high enough.

Dynamic map units are loaded and unloaded on-the-fly. Their name is suffixed with _Dynamic. The dynamic loading capability is only really put to good use for open-world type stages (e.g. MainField and AocField). In such map units, the link system cannot be used and only map objects can be specified. Dynamic units are considered to be loaded once the player is either inside of the map they are placed (always the case for CDungeon and MainFieldDungeon), or the player is (on MainField and AocField) located in one of the map-sections around the map-section the unit is placed in.

Example: Player is located in H-5 so G-4, H-4, I-4, G-5- I-5, G-6, H-6 and I-6 dynamic units are loaded in memory and will be displayed if the TraverseDist is high enough.

Contents

LocationPosX

X coordinate of the center of the map unit.

LocationPosZ

Y coordinate of the center of the map unit.

LocationSize

Size of the map unit (side length of the square).

Objs

Array of object structures. Must be sorted by HashId[1] because the placement subsystem performs binary searches on the object array in various cases[2].

Rails

Array of rail structures. Can only appear in group 0 maps (Static); this section is completely ignored for non-static map units.

There are two primary types of Rails.

Name Description
NavigationMeshRoad Used by Actors that are dynamically spawned along a route
Guide Used to send an actor through a pre-set route via RailPoints.

Rails utilize nodes (NavigationMeshRoadPoint and GuidePoint) depending on the type of Rail in use. Rails are also configured to use a linear or Bezier rail type.

Node
Param Description Example Default Value
IsAdjustPosAndDirToPoint Determines whether the actor will turn and face the next rail point before moving. false false
WaitFrame How long to wait at the current Rail Point. 120.0 0.0
OnFlagName Flag to set to On when the actor arrives at the Rail Point FirstOhenro_Point12
WaitASKeyName If set to wait, the AS to use whilst waiting. Surprised
Next Distance The Distance between the current Rail Point and the next one. 1.0853188 0.0
PrevDistance The Distance between the current Rail Point and the previous one. 31.7270927 0.0
Scale Size of Rail 0, 0, 0
Rotate Rotation of the Rail Point 0, 0, 0
Translate The position of the Rail Point [38.73703, 280.20105, -2438.69751] 0, 0, 0
ControlPoints
UnitConfigName The Type of Rail Point GuidePoint


Link system

In static map units only, map objects can be linked to other objects (up to 255 in a single generation group[3]). These links allow implementing custom logic and callbacks. For example, DeadUp signals the destination object when the source object dies. This is used to implement enemy chests that only unlock after clearing an enemy camp.

LinkTags and other tag objects are lightweight actors that are used to link objects together.

Objects that are linked together, either directly or via indirect links, are put into the same generation group and loaded at the same time[check]. If the placement system fails to load an actor, the entire generation group is discarded.

Definitions

Cs means Constraint[4].

ID Name Description Official description
4 -AxisX - マイナスX軸シグナル
5 -AxisY - マイナスY軸シグナル
6 -AxisZ - マイナスZ軸シグナル
24 AreaCol Area collision (link target is an Area object) エリア(センサ)指定
1 AxisX - X軸シグナル
2 AxisY - Y軸シグナル
3 AxisZ - Z軸シグナル
37 BAndSCs Ball & Socket constraint ボール&ソケットCS
38 BAndSLimitAngYCs Y angular velocity limited Ball & Socket constraint Y角速度制限付ボール&ソケットCS
0 BasicSig Basic signal 基本シグナル
9 BasicSigOnOnly Basic signal [only emits ON signals] オンのみ基本シグナル
14 ChangeAtnSig Signal on Attention change (e.g. picking up a weapon) アテンション変更時シグナル
39 CogWheelCs Gear/cogwheel constraint 歯車CS
21 CopyWaitRevival Activate links when the revival flag of the CopyWaitRevival target is set (e.g. can be used with LinkTagAnd to trigger basic signals when a chest is opened) 配置自動セーブ継承
15 Create Create a map object. Target objects are not created unless this link is activated. 生成
11 DeadUp Signal on death 死んだらオン
16 Delete Delete a map object. Target objects are created and stay spawned until this link is activated. Note: the corresponding collision is disabled even for objects that have their collision data extracted to separate Static Compound files. 削除
29 DemoMember - デモ参加
32 FixedCs Rigid connection constraint 固定CS
26 ForSale Links a shop item to its seller (target is the seller NPC). 売り物
19 ForbidAttention Prevent attention (i.e. interacting with an object, for example picking up a weapon) アテンションタイプ変更
18 Freeze Freeze the target object 凍結
7 GimmickSuccess Success signal (used for minigames) ネタ成功シグナル
33 HingeCs Hinge constraint ヒンジCS
12 LifeZero Emit a LifeZero signal when the life of the source object is 0 ライフ0
34 LimitHingeCs Limited hinge constraint 制限付ヒンジCS
27 ModelBind - モデルバインド
17 MtxCopyCreate - 位置継承生成
22 OffWaitRevival Reset the revival flag of the target object 配置自動セーブオフ
30 PhysSystemGroup - 物理システムグループ
28 PlacementLOD Replace the source object with the link target object at lower level of details 配置LOD
36 PulleyCs - 滑車CS
40 RackAndPinionCs Rack-and-pinion constraint ラック&ピニオンCS
23 Recreate Recreates the target object 再生成
41 Reference - 参照
10 Remains Divine Beast signal 遺物シグナル
25 SensorBind - センサバインド
35 SliderCs Slider constraint スライダーCS
13 Stable - 安定
31 StackLink - スタック
20 SyncLink Put the destination object and any object that is linked to it into the same generation group 生成グループ
8 VelocityControl Velocity control signal 速度制御シグナル

Link tags

Not to be confused with actor tags.

LinkTagAnd, LinkTagOr, LinkTagNAnd, LinkTagNOr, LinkTagXOr, LinkTagCount, LinkTagPulse, LinkTagNone are small objects that are used to implement a basic logic system in map units.

AND, OR, NAND, NOR, XOR LinkTags are logical operators. They can be used to conditionally set or clear GameData flags, or conditionally spawn objects, trigger other objects, etc. A basic signal is emitted when the LinkTag has been triggered by all of the source links (for LinkTagAnds) or by one of them (for LinkTagOrs), etc.

Count LinkTags are used to increment a GameData flag every time the link tag itself is signalled.

Pulse LinkTags continuously emit a basic signal with a configurable signal duration (PulseLength)[5].

None LinkTags have no effect. They are only used to put different map unit objects into the same placement generation group.

Internally, they are all implemented by the same actor class (LinkTag) since they share most of their core functionality, with only small differences in effects. A single link tag can only handle 0x60 incoming links[6]. Only incoming links with defType <= 0xe are processed[7]; other links are ignored.

Parameters are documented in AIDef:Action/LinkTagBaseAction.

File formats

Map unit binary

In Breath of the Wild, map units are stored in a binary format and given the mubin (Map Unit Binary) file extension. All map object IDs are replaced with CRC32 hashes as a space optimisation. BYML is used as the serialisation format.

Map units can be found in the Map content directory, and use the following naming convention: Map/%s/%s/%s%s.mubin (map type, map name, map name, suffix).

Despite the file extension, Map/%s/Location.mubin and Map/%s/LazyTraverseList.mubin are not actually map units.

Source map unit

Source map units have muunt[8] as their file extension and use strings for map object IDs such as F-5_challenge.muunt/obj760 instead of CRC32 hashes of the IDs in map unit binaries.

  1. Technically, sorting is only required for Dynamic (non-group 0) map units. However, not sorting causes the game to fall back to a slower linear search.
  2. 0x7101256E14
  3. "一つの生成グループに 255 以上のアクタが指定されています。テストで無ければプログラマに相談"
  4. SliderCs links are handled by a function 0x7100F70D60 [nx-1.5.0 executable] that is also called by AIDef:Action/SwitchStepSliderConstraint
  5. This appears to require a BasicSig input and does not repeat automatically. In order to get this behavior, fire it with a SwitchTimer.
  6. 0x7100D388C4
  7. 0x7100D389DC
  8. The executable has remnants of error logging functions that print paths to development map units of the following type: Map/Project/%s/Data/%s/%s.muunt