This is an article about the legacy Sapien for use with Halo: Custom Edition, for the H1A Sapien for MCC see H1A Sapien

Sapien, part of the HEK, 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 which supports many more debug commands than the in-game one.

Menu options

Switch BSP

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.

Windows

Game window

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 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

Camera rotation with the G key is only supported in-game and not in Sapien.

Hierarchy view

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.

Tool window

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.

Properties palette

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.

Output window

This window is unused and can be ignored.

Keyboard shortcuts/hotkeys

Some of these shortcuts are only used in certain windows or editor modes.

General

  • ~: Opens the command console.
  • 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. This hotkey is broken in the Gearbox HEK release and can cause Sapien to crash when restarted. Do not use it! It also causes editor icons and name overlays to disappear for the session. This issue is fixed in H1A Sapien.

Encounters and AI

  • 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 ai_select <encounter>.
  • 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:
    • Actions
    • Activation status
    • None
  • Middle mouse + F6: Erase all spawned actors, e.g. those created with ai_place.
  • 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.

Recorded animations

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
    • Flycam
  • 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

Detail objects painting

  • Shift + Right Click: Erases all detail objects in a highlighted cell.
  • Shift + Control + Right Click: As above, but also deleted the cell itself.
  • Shift + Control + L: Relight detail objects (useful after updating lightmaps).

Radiosity

Both Tool and Sapien can be used to generate lightmaps. 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 LM_Tool is recommended for high quality lightmaps since it is easier to control the stop parameter (when to save) and is faster than using Sapien or Tool.

editor_init.txt

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

Compatibility

Windows users have experienced saving issues related to the Virtual Store. Ensure you have the right permissions before editing tags.

On Linux, Sapien can be run successfully using Wine but is not yet compatible with DXVK. Use built-in or standard native DirectX libraries instead.

Limits

As an older 32-bit Windows application, Sapien is limited to 2 GB of virtual memory even on modern 64-bit Windows systems for compatibility. While this memory limit is usually not an issue, an abundance of large textures and other large assets in a map may cause Sapien to crash. To work around this, sapien.exe can be patched to tell the OS it supports 4 GB of virtual memory (large address aware, or LAA) using a utility like NTCore. To do this:

  • Install NTCore 4GB Patch
  • Run the 4GB Patch.
  • Select the Sapien executable.
  • NTCore will apply the patch. After it's finished, press OK. Sapien has now been patched to support 4 GB of virtual memory.

H1A Sapien is already LAA.

Troubleshooting

Interface

IssueSolution
The game window is completely black and does not display the console when ~ (tilde) is pressed.Sapien, like Halo, does not support MSAA. Add Sapien as a program in your graphics control panel and disable anti-aliasing for it. Fixed in H1A Sapien
The "edit types" window does not allow tags to be added.Unknown. Potential issue with Windows compatibility modes. Try running without a compatibility mode.
Child windows are not visible or stuck outside the main window.Open the registry key HKEY_USERS\S-1-5-21-0-0-0-1000\Software\Microsoft\Microsoft Games\Halo HEK\sapien (user ID may vary) using regedit and delete all entries ending with "rect".
Sapien debug wireframe colors and bounding radii change at angles and turn black, making it hard to identify their types.None known for Gearbox Sapien, fixed in H1A Sapien

Crashes

When Sapien crashes, check debug.txt for hints. You can ignore Couldn't read map file './sapienbeta.map'.

Error

Solution

\halopc\haloce\source\rasterizer\dx9\rasterizer_dx9_hardware_bitmaps.c(148): E_OUTOFMEMORY in IDirect3DDevice9_CreateTexture(global_d3d_device, width, height, bitmap->mipmap_count+1-mip_levels_to_drop, 0, rasterizer_bitmap_format_table[bitmap->format], D3DPOOL_MANAGED, &(IDirect3DTexture9*)bitmap->hardware_format, NULL) (code=-2147024882, error=<can't get description>) 10.01.19 17:07:33  couldn't allocate #1398128 tag data for 'bitmap_pixel_data'

You are running out of memory. Try freeing up more physical memory on your system, and/or using a large address aware Sapien.

EXCEPTION halt in \halopc\haloce\source\sound\sound_dsound_pc.c,#1940: properties->gain>=0.f && properties->gain<=1.f

This is probably not an issue with your tags, but rather Sapien failing to initialize its sound system (perhaps after device changes or system sleep). Restart your system or put sound_enable 0 into Sapien's editor_init.txt if you don't need to hear sounds in Sapien for now. Also ensure you don't have any scripts setting sound_set_music_gain over 1.

\halopc\haloce\source\rasterizer\dx9\rasterizer_dx9_hardware_bitmaps.c(148): E_OUTOFMEMORY in IDirect3DDevice9_CreateTexture(global_d3d_device, width, height, bitmap->mipmap_count+1-mip_levels_to_drop, 0, rasterizer_bitmap_format_table[bitmap->format], D3DPOOL_MANAGED, &(IDirect3DTexture9*)bitmap->hardware_format, NULL) (code=-2147024882, error=<can't get description>)

You have a bitmap tag which is too large. Do not exceed dimensions of 2048 pixels because support is GPU-dependent; technically DirectX 9 did not allow sizes over this limit. This issue is fixed in H1A Sapien as it updated to DX11 which doesn't have this issue.

EXCEPTION halt in .\\\\detail_object_tool_handler.cpp,#103: &diffuse_color: assert_valid_real_rgb_color(-9.395227, -3.398408, -2.530689)

A detail object was painted outside the map. Be careful when painting around corners and small spaces, and save frequently.

EXCEPTION halt in /halopc/haloce/source/cseries/profile.c,#442: parent_timesection->self_msec >= child_timesection->elapsed_msec

This may be caused by a multi-core processor. Try running in Windows 98 compatibility mode, or setting the process affinity to a single core using Task Manager before opening the scenario. This issue is fixed in H1A Sapien.

EXCEPTION halt in \halopc\haloce\source\rasterizer\rasterizer_transparent_geometry.c,#137: group->sorted_index>=0 && group->sorted_index<transparent_geometry_group_count

An object has transparent self occlusion enabled while also referencing a transparent shader with extra layers. This is not a problem in-game. This issue is fixed in H1A Sapien.

EXCEPTION halt in \halopc\haloce\source\rasterizer\dx9\rasterizer_dx9.c,#2014: global_window_parameters.fog.planar_maximum_depth>0.0f

Try moving or resizing your fog plane(s).

EXCEPTION halt in \halopc\haloce\source\tag_files\tag_groups.c,#2419: group_tag==NONE || tag_group_get(group_tag)

Sapien has encountered an unrecognized tag class, such as an OpenSauce tag or vestigial tag. Remove references to this tag class.

EXCEPTION halt in .\hierarchy_items.cpp,#2030: can_add_manually

You clicked "New instance" when the button is meant to be disabled. Fixed in H1A.

>EXCEPTION halt in \halopc\haloce\source\tag_files\tag_groups.c,#3157: #0 is not a valid shader_transparent_chicago_map_block index in [#0,#0)

Your map uses a transparent shader with no maps defined. Add at least 1.

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.

EXCEPTION halt in \halopc\haloce\source\tag_files\tag_groups.c,#3142: offset>=0 && offset+size<=data->size

You may have a corrupted sound tag which was extracted with HEK+. Always use invader-extract instead.

Acknowledgements

Thanks to the following individuals for their research or contributions to this topic:

  • aLTis (Relight detail object collections tip)
  • GAIGHER (Multi-core crash solution)
  • General_101 (Additional Sapien hotkey documentation)
  • gruntfromhalo (Discovering fog plane fix)
  • InfernoPlus (Sound gain crash solution)
  • Jakey (Known issues, transparent self occlusion crash explanation)
  • kirby_422 (Describing baggage.txt file)
  • Real Fake Doors (Sharing NT Core knowledge)
  • The Cereal Killer (Discovering Sapien keyboard shortcuts)