Importing MCC Tags - grimdoomer/Prometheus-Info GitHub Wiki

Prometheus can be used to import and convert tags from the Halo 2 MCC editing kit to Xbox format. Currently Prometheus is only compatible with the October 2021 version of the Halo 2 MCC HEK. Tag files created with newer versions of the Halo 2 MCC HEK are most likely compatible with the 2021 version of the HEK, and thus Prometheus, but I have not thoroughly tested this myself. For instructions on how to download the October 2021 version of the Halo 2 MCC HEK see Configuring MCC Support.

Compatibility/Feature Support

Prometheus supports importing most of the tag types the HEK supports with a few exceptions. The following tag types cannot be imported into Prometheus:

  • shader_template
  • shader_pass
  • vertex_shader

Not all tag types have been tested for import so you may encounter issues with any tag types that haven't been tested yet. Additionally, some tag types require additional conversion logic during import and may not function in-game as expected even if they are imported successfully. Any issues encountered with imported tags should be reported so I can attempt to add and refine the import process.

Additionally, the following items have been tested and are mostly functional/supported, though your results may vary:

  • Scripts
  • AI Pathfinding
  • Custom models, collision models, physics models, and animations
  • Converting singleplayer and multiplayer scenarios

The following items have been tested with varrying degrees of success:

  • Custom sounds

Lightmap Compatibility

Before importing a BSP you must make sure it has a lightmap in the P8 format compatible with Xbox. The stock tags that come with the MCC HEK use lightmaps in the "truecolor" format which is not compatible with Xbox. You can check if the BSP already has a P8 format lightmap bitmap tag by looking for a tag in the same folder as the bsp with the name <scenario name>_<bsp name>_lightmap_bitmaps.bitmap, ex: street_sweeper_street_sweeper_lightmap_bitmaps.bitmap.

image

If you only see a bitmap tag with "truecolor" in the name you'll need to regenerate the lightmap. To fix this you can simply generate a new lightmap for the BSP which will create lightmap bitmap tags in both formats, no further changes are required. You can generate a new lightmap using the following command from within the MCC HEK directory:

tool.exe lightmaps <scenario> <bsp> <quality>

Example:
tool.exe lightmaps "scenarios\multi\street_sweeper\street_sweeper" street_sweeper low

Map Design Considerations

Due to Prometheus lacking various features as well as some technical limitations of it's ability to compile map files there's several things you'll want to consider when importing tags from MCC.

Shader Compatibility

All shaders used should use one of the supported shader templates listed in the Shader Compatibility Issues section. Some converted shaders may have graphical issues compared to the MCC counterpart. These issues should be reported so I can continue to improve the conversion functionality.

Texture Resolution

It's recommended to avoid larger texture resolutions when making your map as the Original Xbox has limited memory (though you can if you want). You'll also want to avoid formats like A8R8G8B8 as these are uncompressed and larger in size. Recommended texture sizes are no larger than 1024x1024 (potentially use lower resolutions for detail maps), and use DXT 1/3/5 compressed formats.

Scenery Collision Models

When building a map with scenery placements you'll need to do all the placement editing in Sapien before importing the map to Prometheus. Scenery is a special case in Halo 2 and the player collision mesh for it actually gets compiled into the bsp collision mesh. Therefore, the scenery must be placed in it's final location before importing and trying to move or rotate it in Prometheus afterwards can cause the object to lose player collision.

AI Pathfinding

AI pathfinding data can be generated for a BSP in Sapien and imported into Prometheus. Currently Prometheus doesn't have support for editing AI spawns and firing positions so you'll want to place these in Sapien before importing into Prometheus.

Importing Tags

Note

All tags to be imported must be in the tags folder for the HEK tools directory Prometheus is configured to use. You cannot import tags from another folder or HEK tools directory.

Note

Right now all tags must be imported via a scenario tag, so if you only want to import something like a custom model you'll need to find a way to "shuttle" it through a scenario tag, ex: creating a scenario tag that references a crate tag that references your model.

Note

Any BSP that's imported must have a corresponding lightmap associated with it. Importing a BSP with no lightmap is currently not supported. The lightmap must also be in P8 format as the "truecolor" format is not supported on Xbox. Generating a new lightmap for a bsp will automatically create lightmap bitmap tags in both formats, no additional changes are required.

Note

Only the first BSP linked in a scenario will be imported. Importing more than 1 BSP at a time is currently not supported but will be added in the future.

Importing tags from the MCC HEK can be done with the following steps:

  1. In Prometheus open the tag repository you want to import the HEK tags into.

  2. Click on File->Import->HEK Tags. In the import dialog browse and select the HEK scenario tag you want to import.

  3. Click Next and Prometheus will analyze the scenario and referenced tags. Once the analysis is complete a list of any warnings/errors that were found will be displayed. These issues can include things like missing or incompatible tags, unsupported shader templates found, etc. These issues won't prevent you from importing your tags but it's recommended you fix them before import for best results. If you see errors about the lightmap not being compatible you'll need to regenerate an Xbox compatible lightmap using the instructions in the Lightmap Compatibility section. image

  4. In the Import Options section you'll be given a list of tags found from analyzing the scenario and can pick which tags to import. By default all tags that are not part of the stock tag list will be displayed and selected. Existing tags in the tag repository will be overwritten during import. Once you have selected the tags you want to import you can click Next.
    image

Note

Prometheus currently does not support importing modified versions of stock tags. If you want to import modified versions of stock tags you'll need to rename them in the HEK before trying to import them.

  1. After clicking next the import process will start, this process will take several minutes to complete depending on how many tags you have selected for import. image

  2. After the import process finishes you'll be able to find your imported tags in the active tag repository. You can also find a "HEKImportLog.txt" log file in the Logs folder of Prometheus application directory that can be used to diagnose issues encountered during the import process.

Known Issues and Compatibility Problems

There's a number of issues and compatibility problems that can arise when importing tags from the MCC HEK. Please refer to the following sections for known issues and workarounds.

Shader Compatibility Issues

Due to MCC running on PC and using a newer version of DirectX all imported shader tags must go through a special conversion process to be compatible with the Xbox version of the game. In order for a shader to be compatible for import it must use a shader template that is supported on both the Xbox and MCC version of the game. While I have done preliminary testing on these shader templates there may still be issues such as incorrect texture tiling/scaling, incorrect color sampling, etc. Please see below for more information on how to identify and report such issues.

Shaders based on the following shader templates are currently supported:

effects\screen_effects\blur.shader_template
effects\screen_effects\desaturate.shader_template
shaders\shader_templates\decorators\decorator_decal_paint.shader_template
shaders\shader_templates\decorators\decorator_decal_paint_multiply.shader_template
shaders\shader_templates\decorators\decorator_tex.shader_template
shaders\shader_templates\dynamic_light_gels\plasma_light_gel.shader_template
shaders\shader_templates\hologram\hologram.shader_template
shaders\shader_templates\hud\dashlight_generic.shader_template
shaders\shader_templates\hud\player_training.shader_template
shaders\shader_templates\hud\shield_test.shader_template
shaders\shader_templates\hud\text_flash.shader_template
shaders\shader_templates\hud\waypoint_arrow.shader_template
shaders\shader_templates\hud\waypoint_arrow_meter.shader_template
shaders\shader_templates\hud\waypoint_emblem.shader_template
shaders\shader_templates\hud\waypoint_icon_meter.shader_template
shaders\shader_templates\hud\widget_gradient_flash.shader_template
shaders\shader_templates\hud\widget_legacy_meter.shader_template
shaders\shader_templates\hud\widget_meter_custom.shader_template
shaders\shader_templates\hud\widget_simple_custom.shader_template
shaders\shader_templates\hud\widget_simple_flash.shader_template
shaders\shader_templates\opaque\active_camo_opaque.shader_template
shaders\shader_templates\opaque\decal_simple.shader_template
shaders\shader_templates\opaque\emblem_flag.shader_template
shaders\shader_templates\opaque\emblem_overlay_simple.shader_template
shaders\shader_templates\opaque\illum.shader_template
shaders\shader_templates\opaque\illum_3_channel.shader_template
shaders\shader_templates\opaque\illum_3_channel_opaque.shader_template
shaders\shader_templates\opaque\illum_3_channel_plasma.shader_template
shaders\shader_templates\opaque\illum_bloom.shader_template
shaders\shader_templates\opaque\illum_bloom_3_channel_opaque.shader_template
shaders\shader_templates\opaque\illum_bloom_masked.shader_template
shaders\shader_templates\opaque\illum_bloom_opaque.shader_template
shaders\shader_templates\opaque\illum_clamped.shader_template
shaders\shader_templates\opaque\illum_detail.shader_template
shaders\shader_templates\opaque\illum_opaque.shader_template
shaders\shader_templates\opaque\overlay.shader_template
shaders\shader_templates\opaque\prt_lightmap.shader_template
shaders\shader_templates\opaque\prt_scarab.shader_template
shaders\shader_templates\opaque\prt_simple.shader_template
shaders\shader_templates\opaque\prt_simple_lm_emissive.shader_template
shaders\shader_templates\opaque\render_layer_disabled.shader_template
shaders\shader_templates\opaque\tex_alpha_test.shader_template
shaders\shader_templates\opaque\tex_bump.shader_template
shaders\shader_templates\opaque\tex_bump_active_camo.shader_template
shaders\shader_templates\opaque\tex_bump_alpha_test.shader_template
shaders\shader_templates\opaque\tex_bump_alpha_test_clamped.shader_template
shaders\shader_templates\opaque\tex_bump_alpha_test_clamped_single_pass.shader_template
shaders\shader_templates\opaque\tex_bump_alpha_test_single_pass.shader_template
shaders\shader_templates\opaque\tex_bump_detail_blend.shader_template
shaders\shader_templates\opaque\tex_bump_detail_blend_detail.shader_template
shaders\shader_templates\opaque\tex_bump_detail_blend_specular.shader_template
shaders\shader_templates\opaque\tex_bump_detail_blend_specular_combined.shader_template
shaders\shader_templates\opaque\tex_bump_detail_blend_specular_dblmult.shader_template
shaders\shader_templates\opaque\tex_bump_detail_keep.shader_template
shaders\shader_templates\opaque\tex_bump_detail_keep_blend.shader_template
shaders\shader_templates\opaque\tex_bump_detail_overlay.shader_template
shaders\shader_templates\opaque\tex_bump_dprs_env.shader_template
shaders\shader_templates\opaque\tex_bump_dprs_env_illum.shader_template
shaders\shader_templates\opaque\tex_bump_env.shader_template
shaders\shader_templates\opaque\tex_bump_env_alpha_test.shader_template
shaders\shader_templates\opaque\tex_bump_env_alpha_test_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_alpha_test_indexed.shader_template
shaders\shader_templates\opaque\tex_bump_env_clamped.shader_template
shaders\shader_templates\opaque\tex_bump_env_clamped_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_detail_blend_specular.shader_template
shaders\shader_templates\opaque\tex_bump_env_detail_overlay.shader_template
shaders\shader_templates\opaque\tex_bump_env_detail_overlay_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_fast_masked.shader_template
shaders\shader_templates\opaque\tex_bump_env_four_change_color.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_3_channel.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_3_channel_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_3_channel_combined_unfucked.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_3_channel_occlusion_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_detail_honor_guard.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_four_change_color_no_lod.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_tiling_specular.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_two_change_color.shader_template
shaders\shader_templates\opaque\tex_bump_env_illum_two_change_color_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_no_detail.shader_template
shaders\shader_templates\opaque\tex_bump_env_tiling_specular.shader_template
shaders\shader_templates\opaque\tex_bump_env_two_change_color.shader_template
shaders\shader_templates\opaque\tex_bump_env_two_change_color_combined.shader_template
shaders\shader_templates\opaque\tex_bump_env_two_change_color_indexed.shader_template
shaders\shader_templates\opaque\tex_bump_env_two_change_color_multiply_map_self_illum.shader_template
shaders\shader_templates\opaque\tex_bump_env_two_detail.shader_template
shaders\shader_templates\opaque\tex_bump_env_two_detail_combined.shader_template
shaders\shader_templates\opaque\tex_bump_four_change_color.shader_template
shaders\shader_templates\opaque\tex_bump_illum.shader_template
shaders\shader_templates\opaque\tex_bump_illum_3_channel.shader_template
shaders\shader_templates\opaque\tex_bump_illum_alpha_test.shader_template
shaders\shader_templates\opaque\tex_bump_illum_alpha_test_illum.shader_template
shaders\shader_templates\opaque\tex_bump_illum_alpha_test_single_pass.shader_template
shaders\shader_templates\opaque\tex_bump_illum_bloom.shader_template
shaders\shader_templates\opaque\tex_bump_illum_detail.shader_template
shaders\shader_templates\opaque\tex_bump_illum_detail_honor_guard.shader_template
shaders\shader_templates\opaque\tex_bump_illum_no_specular.shader_template
shaders\shader_templates\opaque\tex_bump_meter_illum.shader_template
shaders\shader_templates\opaque\tex_bump_one_change_color.shader_template
shaders\shader_templates\opaque\tex_bump_plasma.shader_template
shaders\shader_templates\opaque\tex_bump_plasma_one_channel_illum.shader_template
shaders\shader_templates\opaque\tex_bump_shiny.shader_template
shaders\shader_templates\opaque\tex_bump_three_detail_blend.shader_template
shaders\shader_templates\opaque\tex_bump_tiling_specular.shader_template
shaders\shader_templates\opaque\tex_bump_two_change_color.shader_template
shaders\shader_templates\opaque\tex_bump_two_detail.shader_template
shaders\shader_templates\opaque\tex_detail_blend.shader_template
shaders\shader_templates\opaque\tex_env.shader_template
shaders\shader_templates\opaque\tex_env_3_channel_illum.shader_template
shaders\shader_templates\opaque\tex_illum.shader_template
shaders\shader_templates\opaque\tex_illum_bloom.shader_template
shaders\shader_templates\particle\particle_alpha_test.shader_template
shaders\shader_templates\texture_camera\scope.shader_template
shaders\shader_templates\transparent\add_illum_detail.shader_template
shaders\shader_templates\transparent\cortana.shader_template
shaders\shader_templates\transparent\lit\transparent_lit_alpha_blend_two_change_color.shader_template
shaders\shader_templates\transparent\meter.shader_template
shaders\shader_templates\transparent\meter_active_camo.shader_template
shaders\shader_templates\transparent\one_add_env_illum.shader_template
shaders\shader_templates\transparent\one_add_env_illum_clamped.shader_template
shaders\shader_templates\transparent\one_add_illum.shader_template
shaders\shader_templates\transparent\one_add_illum_detail.shader_template
shaders\shader_templates\transparent\one_add_illum_no_fog.shader_template
shaders\shader_templates\transparent\one_alpha_env.shader_template
shaders\shader_templates\transparent\one_alpha_env_active_camo.shader_template
shaders\shader_templates\transparent\one_alpha_env_clamped.shader_template
shaders\shader_templates\transparent\one_alpha_env_fixed.shader_template
shaders\shader_templates\transparent\one_alpha_env_illum.shader_template
shaders\shader_templates\transparent\one_alpha_env_illum_specular_mask.shader_template
shaders\shader_templates\transparent\one_alpha_env_plasma.shader_template
shaders\shader_templates\transparent\overshield.shader_template
shaders\shader_templates\transparent\overshield_tartarus.shader_template
shaders\shader_templates\transparent\particle_additive.shader_template
shaders\shader_templates\transparent\particle_additive_tint.shader_template
shaders\shader_templates\transparent\particle_alpha_blend.shader_template
shaders\shader_templates\transparent\particle_plasma.shader_template
shaders\shader_templates\transparent\plasma_alpha.shader_template
shaders\shader_templates\transparent\plasma_alpha_active_camo.shader_template
shaders\shader_templates\transparent\plasma_mask_offset.shader_template
shaders\shader_templates\transparent\plasma_shield.shader_template
shaders\shader_templates\transparent\plasma_shield_change_color.shader_template
shaders\shader_templates\transparent\sky_one_add_two_plus_two.shader_template
shaders\shader_templates\transparent\sky_one_alpha_env.shader_template
shaders\shader_templates\transparent\sky_one_alpha_env_clamped.shader_template
shaders\shader_templates\transparent\sky_one_alpha_env_illum.shader_template
shaders\shader_templates\transparent\sky_two_add_clouds.shader_template
shaders\shader_templates\transparent\sky_two_add_clouds_clamped.shader_template
shaders\shader_templates\transparent\sky_two_alpha_clouds.shader_template
shaders\shader_templates\transparent\two_add_clouds.shader_template
shaders\shader_templates\transparent\two_add_detail_masked.shader_template
shaders\shader_templates\transparent\two_add_detail_masked_prepass.shader_template
shaders\shader_templates\transparent\two_add_env_illum.shader_template
shaders\shader_templates\transparent\two_add_env_illum_3_channel.shader_template
shaders\shader_templates\transparent\two_add_env_illum_active_camo.shader_template
shaders\shader_templates\transparent\two_alpha_clouds.shader_template
shaders\shader_templates\transparent\two_alpha_detail_masked.shader_template
shaders\shader_templates\transparent\two_alpha_env_detail.shader_template
shaders\shader_templates\transparent\two_alpha_env_illum.shader_template
shaders\shader_templates\transparent\two_alpha_env_illum_bumped_environment_masked.shader_template
shaders\shader_templates\transparent\two_alpha_env_multichannel.shader_template
shaders\shader_templates\transparent\waves.shader_template
shaders\shader_templates\water\ocean_static.shader_template
shaders\shader_templates\water\ocean_static_opaque.shader_template
shaders\shader_templates\water\ocean_static_opaque_blend.shader_template
shaders\shader_templates\water\water_edge_blend.shader_template
shaders\shader_templates\water\water_pool.shader_template
shaders\shader_templates\water\water_pool_static.shader_template
shaders\shader_templates\water\water_static.shader_template

Shaders based on a shader template that doesn't exist in the Xbox version of the game are not supported. Additionally, the following shader templates have been modified on the MCC side and shaders using these shader templates cannot be imported:

shaders\shader_templates\texture_camera\texture_camera.shader_template

Identifying and Reporting Shader Compatibility Issues

Shader issues can be identified by comparing the geometry between Prometheus and MCC side by side. Most of the issues will manifest as tiling/scaling/color related discrepencies. For example, in the following image you can see the texture tiling is incorrect between Prometheus and MCC:

image

If you encounter such issues please report them along with what shader template was used for the shader. In some cases I may request the MCC shader tag you used for additional diagnosis.

Screen Fades to Black After Loading Map

If you try to load a converted map on Xbox and the screen fades to black after the player spawns in this is likely due to the map using the cinematic_snap_to_black script command which doesn't play nicely on Xbox. To work around this issue simply remove any use of this script command.

Scenery Loses Player Collision

Scenery in Halo 2 is a special case and the physics model for it gets compiled into the bsp collision model. If you try to add/move/rotate scenery spawns after importing a bsp it will likely lose player collision. The current workaround is to use Sapien for all scenery placement editing before importing the bsp.

⚠️ **GitHub.com Fallback** ⚠️