H1A Sapien (343i)
This page needs help! Please submit any missing information via GitHub issues or pull requests.
H1A Sapien, part of the H1A-EK, is a visual scenario and BSP editor used to populate levels with objects, configure BSP cluster data like wind and sound environments, compile scripts, and more. Sapien shares some systems with Halo itself, including its AI system to support interactive AI scripting and debugging. Other systems, such as weather rendering, are not represented.
It is roughly analagous to Forge found in later Halo titles, although the user cannot interact with the world as a player. Users primarily interact with Sapien's windows and menus, but the Game Window also includes a scripting console.
If you prefer legacy Sapien's
debug_objects 1 default appearance, simply set the following globals:
debug_objects_collision_models 1 debug_objects_bounding_spheres 1 debug_objects_root_node 0
You can even place these in your
editor_init.txt so they are run automatically at startup.
Command line flags can be passed to H1A Sapien at launch to change run-time behavior. These features are experimental and might not work as expected.
-multipleinstancecommand line flag can be used to allow multiple instances of Sapien to be launched at once.
-tags_dircan be used to change the tags and data directories. See using custom content paths.
It is common for singleplayer scenarios to be comprised of multiple BSPs. The Edit > Switch BSP option is used to change between them. Always use this option to switch BSPs and don't use
switch_bsp in the console. The menu option performs additional functions that maintain proper editor state, whereas
switch_bsp is intended for level scripts.
The game window is the main interface when interacting with objects in the level. It is also where you can run commands by pressing the ~ (tilde) key. The resolution and aspect ratio cannot be adjusted.
Movement of the camera is done in the same way as the in-game debug camera; hold the middle mouse button (unless you lock the mouse) plus:
- Use the mouse to aim
- Move with W, A, S, and D
- Go up with R and down with F
- Increase camera speed by scrolling down or pressing Shift
- Decrease camera speed by scrolling up
- Temporarily boost camera speed by holding Ctrl (new in H1A Sapien)
Camera rotation with the G key is only supported in-game and not in Sapien. If you have accidentally opened the singleplayer pause menu, it can be closed again with Middle mouse + Escape.
New in H1A Sapien, you can also use a gamepad to control the camera:
- Right stick click: toggle gamepad control
- Right stick: aiming
- Left stick: horizontal movement
- Right trigger: move up
- Left trigger: move down
- Left stick click: speed boost
- D-pad up/down: speed increase/decrease (make sure to enable
Known issues with gamepad camera control include low aiming sensitivity, lack of stick deadzones, slowness of vertical movement, and speed control framerate dependence.
The Hierarchy view displays all the objects currently placed in the game and organizes them by type. The left pane of the window shows the Hierarchy tree and currently selected type, and the right pane shows the objects of this selected group or type that are currently placed in the level.
This window contains settings for the currently active tool mode, such as object placement, detail object painting, or cluster properties application. The currently active tool depends on the selected hierarchy view item.
The most commonly used settings, or options that are modified the most, are the options under the Active marker handles section and the Don't draw center marker option.
The Properties palette window displays the properties for the currently selected hierarchy item. The type of object can be changed or chosen in this display as well as various other properties such as the position and rotation of the object, and spawn flags that set various attributes for the object.
When applying cluster properties, the camera location in the game window determines the active cluster shown in this window.
This window is unused and can be ignored.
Some of these shortcuts are only used in certain windows or editor modes.
- ~: Opens the command console, pressing it again or pressing enter on an empty console will close it.
- Space: clones the selected object to the camera's location and orientation. If multiple objects are selected, uses the first.
- Pause/Break: Pauses your Sapien instance. Press "OK" in the opened window to resume Sapien.
- Control + B: Open the BSP switch dialog window.
- Control + Shift + B: Creates the file
baggage.txt. If you end up getting a maximum tag slots error or are running low on tag space, this file shows the memory usage of tags in the editor.
- Shift + Click: Select a group of objects or keep previously placed objects selected. You can also use it to select the first and last object in the hierarchy list to select everything in-between at once. Useful for deleting multiple objects or moving them all at once.
- Control + Click: Select a group of objects or keep previously placed objects selected. This will only select the object you specifically click in the hierarchy list. Useful for deleting multiple objects or moving them all at once.
- Hold Tab: Using this key combo while having an object selected will set the rotation gizmo to sync with the local rotation of the object. Only really useful if "Local Axes" is not enabled.
- In the hierarchy view, pressing a key will cycle through all folders that start with that character. For example, pressing A while having the "Missions" folder expanded will immediately take you to the "AI" folder.
- N: This hotkey will snap a selected object to the normal of the ground below it.
- Middle mouse + F1: Selects the spawned actor in the center of the game view.
- Middle mouse + F2 Select next encounter. You can also use the console command
- Middle mouse + F3: Select previous encounter.
- Middle mouse + F4: When an encounter is selected, selects the next actor.
- Middle mouse + Shift + F4: Selects the previous actor.
- Middle mouse + F5: Cycles through render modes for actor sprays:
- Activation status
- Middle mouse + F6: Erase all spawned actors, e.g. those created with
- M: Toggles group labels on firing positions, shows the default actor for move positions used by a squad instance, and highlights editor gizmos/placeholders, making them easier to see.
These hotkeys apply in scripted camera mode.
- A: Toggle "Attach camera to unit" option.
- E: Toggle "Edit camera point" option.
- C: Toggle "Scripted camera control".
- Space: Creates a new camera point at the game view camera's location if "Edit camera point" is disabled. If "Edit camera point" is enabled then it instead moves the "Active camera point" to the camera's location.
- Shift + V: Using this key combo while in scripted camera mode will take over (posess) the selected unit.
- Backspace: Cycles through camera types for the posessed unit:
- First person
- Third person
- Caps lock: Start/stop animation recording. Unfortunately it is not possible to control the posessed unit while recording.
- Shift + Q: Exits a posessed unit while in scripted camera mode.
See main page: recorded-animations
- Shift + Right Click: Erases all detail objects in a highlighted cell.
- Shift + Control + Right Click: As above, but also deleted the cell itself.
Both Tool and Sapien can be used to generate lightmaps. Using H1A Tool is suggested for all but the simplest lightmaps or debugging as it doesn't require as many resources or for the window to be in-focus. To use Sapien, enter the following console commands:
;0 for low quality, 1 for high, or a value like 0.8 radiosity_quality 1 ;begins radiosity. numbers will start to count down radiosity_start ;wait for the numbers to count down to 0 or near 0, then: radiosity_save
If you want progress feedback updated more frequently, you can set
radiosity_step_count 1. See Tool's lightmaps documentation for an explanation of the
radiosity_quality value. Using H1A tool with asserts disabled is strongly recommended for high quality lightmaps since it is easier to control the stop parameter (when to save) and is faster than using Sapien.
At startup, Sapien will load
editor_init.txt if present in the same folder. This file can contain console commands, one per line, which are executed automatically for you. For example:
sound_enable 0 debug_objects 1 ;a comment
Sapien requires DX11 support, it is currently unknown if it can be run under WINE.
|Child windows are not visible or stuck outside the main window.||
Open the registry key
|Can't change the open scenario||This is a known issue, simply close Sapien and open it again; this will allow you to open the scenario.|
|Mouse is locked to game view||Issue/feature with some keyboard layouts, press the middle mouse button to unlock it.|
When Sapien crashes, check
debug.txt for hints.
|EXCEPTION halt in \...\sound\sound_dsound_pc.c,#1966: properties->gain>=0.f && properties->gain<=1.f||Restart your PC and the issue should go away.|
|EXCEPTION halt in \\...\rasterizer\dx9\rasterizer_dx9.c,#1461: global_window_parameters.fog.planar_maximum_depth>0.0f||
Try moving or resizing your fog plane(s).
|EXCEPTION halt in \...\tag_files\tag_groups.c,#3395: group_tag==NONE || tag_group_get(group_tag)|
|EXCEPTION halt in \...\sound\sound_dsound_pc.c,#2083: play_cursor_position >= 0 && play_cursor_position < GetAvgBytesPerSecond(sound_samples_per_second(channel_type_sample_rate(channel->type_flags)), channel_get_num_channels(channel_index))||A sound device was lost or disabled while Sapien was running. Make sure you don't unplug anything and considering using the -nosound argument.|
|EXCEPTION halt in \...\sound\sound_dsound_pc.c,#2151: length <= channel->buffer_size||Same as above|
|EXCEPTION halt in objects.c,#2419: got an object type we didn't expect (expected one of 0x00000001 but got #1).||Attempted to take over a unit in recording mode while no unit was selected. Make sure to select a unit first.|
Thanks to the following individuals for their research or contributions to this topic:
- General_101 (Additional Sapien hotkey documentation and update for H1A.)
- gruntfromhalo (Discovering fog plane fix)
- InfernoPlus (Sound gain crash solution)
- Jakey (Known issues, transparent self occlusion crash explanation)
- kirby_422 (Describing baggage.txt file)
- num0005 (Update for H1A)
- Real Fake Doors (Sharing NT Core knowledge)
- The Cereal Killer (Discovering Sapien keyboard shortcuts)