Skip to content

Configuration#

The game engine has various configuration settings available that tweak how the engine functions.

Implemented Settings#

Directories and Paths (paths)#

Setting name Description Valid values Default Value Type
game_data_root The root of any game files (levels, tags, movies, etc.) any valid relative path . string
user_data_root (No longer used) The path for any user files (game/map variants, config files, savegames, etc.) any valid relative path {$DOCUMENTS}\My Games\Project Infinity string
user_mods_dir The folder to store any user-installed mods, relative to the user content directory. any valid relative path /mods/ string
raw_data_dir The folder to store any miscellaneous loose files, relative to the engine content directory. any valid relative path /content/ string
raw_data_images_dir The folder to store any loose images (.PNG, .GIF, .BMP, .JPG), relative to the engine content directory. any valid relative path /content/Gallery/ string
screenshots_dir The folder to store any user-captured screenshots, relative to the user content directory. any valid relative path /screenshots/ string
levels_dir The folder to store game cache files (.maps), relative to the engine content directory. any valid relative path /maps/ string
fonts_dir The folder to store any game fonts, relative to the engine content directory. any valid relative path /maps/fonts/ string
tags_dir The folder to store any individual tag files that aren't part of any given cache file, relative to the engine content directory. any valid relative path /tags/ string
plugins_dir The folder that XML plugins will be saved to upon being generated, relative to the engine content directory. any valid relative path /plugins/ string
engine_resource_dir The folder to store any miscellaneous engine resources, relative to the engine content directory. any valid relative path /data/ string

Resource Settings (resources)#

Setting name Description Valid values Default Value
force_regenerate_game_engine_text Whether or not to forcibly re-create the default game engine text file, overwriting any user changes true or false true
force_regenerate_globals Whether or not to forcibly re-create the default globals file, overwriting any user changes true or false true

Logger Settings (logging)#

Setting name Description Valid values Default Value Type
clear_log_first Whether or not to clear the log file at startup (only applies for standard logs and reports) true or false true bool
enable_multi_log Whether or not to enable "multi-logging", which creates a new log file for each run true or false true bool
log_format The log format to use, HTML has the option to have stylized logs html, txt, or both html string
multi_log_dir The directory to store multi-logs any valid relative path /logs/ string
reports_dir The directory to store reports any valid relative path /reports/ string
use_reports Whether or not to use reports instead of just debug.txt/debug.html. true or false true bool
stylized_html_logs Whether or not to enable CSS styling for HTML logs true or false true bool
console_color_set The color set to use for the console classic, new, or custom new string
show_header_in_stylized_reports If enabled, the log header will be included even in stylized reports. The header was originally only visible in plain HTML or text logs. true or false true bool
include_extras_in_stylized_reports If enabled, the additional blank line and Ώ ∞ messages will be printed after the header. These serve no purpose other than as a cosmetic feature. true or false false bool
bypass_queue If enabled, the logger queue will not be used outside of initial startup. May cause increased IO usage, but can be used to ensure that no log messages are lost in the event of an exception. true or false false bool

ImGUI Display Settings (imgui)#

Setting name Description Valid values Default Value Type
sys_font The font package to load for ImGUI. Fonts should be placed in /maps/fonts. If sys_font_force_extension is set to true, the file extension must be set to .bin extension, and this config option should be the font name without the extension. Ex: if the font file is "font-package-en.bin", then this value should be "font-package-en". name of any TTF format file in /maps/fonts font_package_dbg string
sys_font_force_extension Whether or not to force a .bin file extension for fonts true or false true bool
sys_font_size The font size to use for ImGUI any float or int 15.0f float
allow_imgui_mouse_change Whether or not to allow ImGUI to change the mouse pointer. true or false false bool

Debug Settings (debug)#

Setting name Description Valid values Default Value Type
hsc_debug Whether or not to print HaloScript parsing details to console true or false false
csc_debug Whether or not to print CommandScript parsing details to console true or false false
screenshot_debug Whether or not to print screenshot debugging details to console true or false false
debugMode Whether or not debug mode is enabled true or false true
placeholder_debug Whether or not to print extra placeholder info to console at startup true or false true
config_colors_debug If enabled, will print a series of dummy messages for each warning severity. Useful for ensuring messages are displaying properly. true or false true
disable_tag_class_version_checking Each time a tag is compiled, the version of the plugin/tag class is embedded into the file. By default, the engine will reject loading any tag compiled with a different plugin version - as doing so will likely result in a crash or other errors. By enabling this setting, the engine will try to load the tag anyways - though a warning is still logged. true or false false bool
disable_tag_fieldset_version_checking Just like with plugin versions, compiled tags also have the fieldset version embedded. The fieldset version refers to the version of the tag fields. If fields types are removed or have their data size changed, the fieldset version is incremented. It is NOT incremented when new fields are added but old ones are unchanged. Setting this to true will allow the engine to load any incompatiable tags, though just like with the plugin version checking - this will likely result in a crash. true or false false bool

Debugging UI (blam_ui) Settings (debug_ui)#

Setting name Description Valid values Default Value Type
ui_default_font The default font package to use for rendering debug text. Name of any font package (.bin) or folder with fontinfo.xml within its root fixedsys_ttf string
always_generate_menubar_file If enabled, then menu_bar_init.xml is forcefully regenerated at startup. Disable this if you wish to customize the menu bar. true or false true bool

Vulkan (Rendering) Settings (rendering)#

Setting name Description Valid values Default Value Type
rendering_engine The rendering engine/graphics API to use. vulkan, directx, opengl, bgfx opengl string
vulkan_log_level Minimum severity for Vulkan log messages to be printed to console. verbose, info, warning, error warning string
vulkan_device The device index of the GPU to use for rendering. auto, first, any valid device index auto string or int

Sentry Settings (sentry)#

Setting name Description Valid values Default Value Type
enable_sentry Whether or not to enable Sentry support. true or false true bool
sentry_host The URL for Sentry to use to send diagnostics data. Any valid Sentry ingest URL. https://[email protected]/5259190 string

Font Settings (fonts)#

Setting name Description Valid values Default Value Type
use_font_table Whether or not to use font_table.txt to retrieve the list of available fonts. true or false true bool
draw_shadow_separately Whether or not to draw text shadow as a separate text object. (?) true or false true bool

Console Settings (console)#

Setting name Description Valid values Default Value Type
extraConsoleOutputPadding Whether or not to keep some space between console output (equal to 1 line) or not. (original games did not have extra spacing) true or false true bool
useEnhancedBooleanCommands Whether or not to use enhanced boolean command handling true or false false bool
useEnhancedGvarMessages Whether or not to use more informative messages for setting script gvars from console. When disabled, messages will display as they did in the original blam! engine. true or false false bool

Debug Menu Settings (debug_menu)#

Setting name Description Valid values Default Value Type
useAlternateDebugMenuUnknownGlobalDisplay Whether or not use an alternative display mode for missing globals in the debug menu. Defaults to false which uses the classic display style seen in blam. true or false false bool
autoGenerateNewDebugMenuFile If enabled, the engine will always re-generate the default debug_menu_init.xml file, even if it already exists. This should be disabled if you wish to customize your debug menu layout or items. true or false true bool

Engine Features (features)#

Setting name Description Valid values Default Value Type
use_discord_rpc Whether or not to enable Discord Rich Presence true or false true bool
show_firstboot Whether or not to show the firstboot dialog true or false true bool
show_windows_menubar Whether or not to show the standard Windows menu bar true or false true bool
use_custom_cursor Whether or not to use the game's custom cursor true or false true bool
enable_imgui_gamepad_nav Whether or not to allow ImGUI to be used with gamepad navigation true or false true bool

Networking Settings (network)#

Setting name Description Valid values Default Value Type
use_netcode Whether or not to enable networking true or false true bool

Multithreading Settings (threading)#

Setting name Description Valid values Default Value Type
use_separate_render_thread Whether or not to run rendering on it's own thread. Changing may have undesirable consequences. true or false true bool

Appearance Settings (appearance)#

Setting name Description Valid values Default Value Type
use_themed_windows Whether or not to use visual themes on dialogs true or false true bool
use_themed_controls Whether or not to use visual themes on dialog controls true or false false bool

Miscellaneous Options (miscellaneous)#

Setting name Description Valid values Default Value Type
screenshot_format The format to use for saving screenshots TBA PNG string

Special Settings - Don't touch these (special)#

Setting name Description Valid values Default Value Type
conf-ver The configuration version, used for upgrading if need be any int 1 int

Placeholders#

Deprecation Notice

The engine Placeholders system is deprecated as of Build #333. Some of the below functionality will be made available through script globals, but will use a different implementation.

Configuration files no longer support placeholders, as they tend to be unreliable and only serve to complicate debugging and diagnostics during early engine initialization - as there is a period of time early on where the placeholder values are not expanded. Additionally, the utility offered by the placeholders system is extremely limited - and the components which can and do benefit from it are better served by game engine globals instead.

This page remains for archival purposes only.

Information on placeholders has been moved here.

Referencing other Config Options#

A configuration value can include the value of another option by using the following format:

{#config_option_id}

Example#

Take the following configuration settings: 

raw_data_dir=content
raw_data_images_dir={#raw_data_dir}\Gallery

raw_data_images_dir would evaluate to:

content\Gallery

Unimplemented Settings#

Info

Many of these settings may not get implemented for reasons that will soon seem obvious. Many of these were conceptualized by a young haloman30 who had little knowledge at the time of how any of this shit works. They describe ambiguous and random features that, in some cases, flat out don't make any sense. They remain here as a reference only in the event that some of these get implemented in the future - just to satisfy that kid's visions and make them into reality (or something like that).

  • fpsMax - Controls the maximum framerate that the engine can run at

    • Valid values: Any number between 1 and 60
    • Default: 60

  • bink-enabled - Whether or not intro videos will play upon starting the game

    • Valid values: true or false
    • Default: true

  • useSwitches - Whether or not to respect command-line switches, such as -console or -devmode

    • Valid values: true or false
    • Default: true

  • useMulti - Whether or not to ignore levels whose scenario path starts with /levels/multi

    • Valid values: true or false
    • Default: true

  • useSolo - Whether or not to ignore levels whose scenario path starts with /levels/solo

    • Valid values: true or false
    • Default: true

  • useLegacyFileStructure - Whether or not to use the traditional Bungie-style file structure /maps, /bink, etc.

    • Valid values: true or false
    • Default: true

  • useDedicated - Whether or not to use Dedicated servers in favor of Peer-to-Peer networking.

    • Valid values: true or false
    • Default: true

  • dedicatedHost - The default host IP for dedicated servers

    • Valid values: any valid DNS hostname or IP address
    • Default: 343.host.elaztek.com

  • dedicatedFallback - A fallback host in the event that the primary dedicated host is offline or unreachable

    • Valid values: any valid DNS hostname or IP address
    • Default: i01.host.elaztek.com

  • dedicatedFallback2 - A secondary fallback host in the event that the primary dedicated host and fallback server are both offline or unreachable

    • Valid values: any valid DNS hostname or IP address
    • Default: contingency.host.elaztek.com

  • ui - The type of UI to use upon starting the game

    • Valid values: default, classic, halo3, imgui
    • Default: default

  • mp3Enabled - Whether or not to support MP3-format sound

    • Valid values: true or false
    • Default: true

  • checkSignatures - Whether or not to check cache file signatures

    • Valid values: true or false
    • Default: true

  • enableElaztekExtended - Whether or not to enable the Elaztek Extended Framework

    • Valid values: true or false
    • Default: true

  • launchMode - The release mode to launch the engine in

    • Valid values: retail, alpha, beta, dev, press, safemode, debug, screen
    • Default: debug

  • init-level - The level to load by default when first starting the game

    • Valid values: any level path
    • Default: levels/ui/mainmenu/mainmenu

  • s_hsc_ver - The HaloScript version that should be used

    • Valid values: any valid release of HSC
    • Default: 15267.10.13.16.0467.blamite

  • havok_cloth_phys - Whether or not to use Havok Cloth simulation

    • Valid values: true or false
    • Default: false

  • havok_impact_phys - Whether or not to use Havok impact simulation

    • Valid values: true or false
    • Default: false

  • havok_physics_engine - The Havok Physics preset to utilize

    • Valid values: havok, h2v, contingencycryengine, madness, none, spaaace, michael
    • Default: none

  • achi_enabled - Whether or not to enable achievement support

    • Valid values: true or false
    • Default: false

  • voice_server - The IP of the TeamSpeak 3 server to utilize for voice communication

    • Valid values: any valid TS IP
    • Default: voice.inf.elaztek.com

  • voice_default_channel - The channel ID to join by default

    • Valid values: any valid channel id
    • Default: 57

  • show_ts_window - Whether or not to show a TeamSpeak window for voice connectivity

    • Valid values: true or false
    • Default: false

  • poly_limit - The maximum number of polygons to render in a given frame

    • Valid values: any valid int16, anything higher will cause issues
    • Default: 32767

  • r_wireframe - Whether or not to render 3D scenes in wireframe mode

    • Valid values: true or false
    • Default: false

  • render_preset - The rendering preset to use by default

    • Valid values: blam, halo, halo2, halo3, omaha, storm, osiris, ue4, unity, groundhog
    • Default: blam

  • fog - Whether or not fog is enabled

    • Valid values: true or false
    • Default: true

  • rendering_engine - The graphics API to utilize for rendering

    • Valid values: directx11, opengl
    • Default: directx11