Skip to content

Package Format

Jump to bottom Edit New page
Spencer Brown edited this page Aug 19, 2025 · 10 revisions

Packages

Packages are container files which hold all needed resources and instructions for a set of items or anything else. They can be either a zip file, or a folder with the same contents. The latter is intended for development use, not for release.

Folder Structure

- <Package>
  - items/
    - <Style>
      - editoritems.txt
      - properties.txt 
      - vbsp_config.cfg
  - styles/
  	- <style>
  - resources/
    - BEE2/
    - instances/
    - materials/
    - music_samp/
    - models/
    - sound/
    - scripts/
  - templates/
  - info.txt

info.txt

All packages must contain an info.txt file located in the zip root. This defines what objects are present inside the package.

"ID" "BEE2_PACK_EXAMPLE"
"Name" "Example Package"
"Prerequisites"
	{
	"Package" "OTHER_PACKAGE_1"
	"Package" "OTHER_PACKAGE_2"
	}

"Item"
	{ ... }
"Override"
	{
	"Item"
		{ ... }
	}

All packages must have a unique ID to identify themseleves. The Name should be a short human-readable string describing the package. This will be displayed in the Manage Packages window in the BEE2. If a package contains a Prerequisites section, all the listed package IDs must be installed. If any are missing, the package will be ignored entirely. This makes it possible to refer to objects or resources in another package, without errors or missing content. As a special case, <MEL_MUSIC> and <TAG_MUSIC> cause a package to only be active if the music for the given game is found.

All other blocks define object types. These must also have an ID to uniquely identify them, but vary in their other contents. If object definitions are placed in an "Overrides" block, they are instead used to 'override' an existing object from another package. The ID should match another object (if no match is found, the definition is ignored). The configuration is merged with the original object config. This can be used to add additional styles to items for example, or otherwise extend objects.

Resources

The resources subfolder contains all the resources needed for the package contents to be used. These will be copied to the correct places as needed. The instances folder is copied to sdk_content/maps/instances/BEE2/, and should hold the instances by items. The BEE2 folder holds PNG images used in the application UI (since the BEE2 cannot currently read VTFs). music_samp should contain short OGG copies of music tracks, for preview in the app. All other folders are directly copied to the game.

Common Properties

Many of the object types (Styles, Music, Quote Packs, Skyboxes and Elevators) share common settings to define their appearance in the selection windows:

  • Name: Specifies the human-readable name for this object.
  • ShortName: Optional, a short version of the name to use if the long variant will not fit on buttons.
  • Group : If set, objects with the same group name will be collected together. This allows grouping similar items.
  • Icon: A path relative to resources/BEE2/ pointing to a 96x96 PNG icon for the object.
  • IconLarge: If set, a second larger (256x192) icon to choose when the item is selected in the menu. This allows showing more detail.
  • Authors: A comma-seperated list of the people who created the specified thing.
  • Description: A description of the object. Limited MarkDown formatting can be used here. This can either be a single string, or multiple in a block, to allow more easily breaking it over multiple lines:
"Description"
	{
	"" "First line of the description."
	"" "Another line of the description."
	...
	}

Object Types

"Item"

Items define items that can appear on the palette. The ID matches the Type in editoritems.txt.

"Item"
	{
	"ID" "ITEM_XXX"
	"Description" ...
	"AllDescLast" "0"
	"needsUnlock" "0"
	
	"Version"
		{
		"ID"   "VER_DEFAULT"
		"Name" "Regular"
		"Styles"
			{
			"STYLE_ID" "folder_name"
			}
		}
	}

"Style"

Styles define the theme of the level. The style definition mainly defines things like the materials used for walls and how a number of features function. Much of the changes are done by switching the configuration used by other package objects like items - exactly how depends on the feature.

A style definition looks like the following:

"Style"
	{
	"ID" "SOME_FANCY_STYLE"
	"Name"			"Super Cool Style"
	"Base" "BORING_STYLE"
	"Description" "Super Cool Style"

	"Folder"		"1950s"
	"Has_Video"		"0"
	"VPK_Name"      "VPK_FANCY_EDITOR"
	"Suggested"
		{
		"Quote"		"FANCY_GLADOS"
		"Skybox"	"PRETTY_FOG"
		"Elev" 		"SPACE"
		"Music"		"COOL_TUNES"
		"Music" 	"ANOTHER_COOL"
		}
	}
  • name, etc: Quote packs show up in selector windows, so they have the Standard set of options.
  • base: The name of another style to 'inherit' from. In most situations, if an object does not have a direct definition, it'll check the base style (and that style's base, etc) for a definition.
  • folder (required): The main configuration info for the style is located here:
    • <folder>/editoritems.txt: This is the initial configuration for the style. Since items have their own configuration, the only things defined here are the ITEM_POINT_LIGHT ambient light entity, and the Renderables block with the error and connection icons.
    • <folder>/vbsp_config.cfg: Configuration for the compiler. Primarily this will contain the texturing definition, style options and potentially some conditions.
  • has_video: Determines if the elevator video selector is enabled or disabled.
  • vpk_name: The ID of a StyleVPK object which is used for the style.
  • suggested: IDs of other object types, which are especially suited for the style. Can be set for Music, Quote, Elev or Skybox. These objects will be highlighted in the menu, and the 'select suggested' button will switch to these.

Music

Music blocks define a specific background music, along with any additional context-specific tracks. WAV files are stored relative to resources/sound/, and are usually in the music/ subfolder of that.

"Music"
{
"ID"            "VALVE_SPACE_PHASE"
"Sample"        "p2/mainmenu/portal2_background05.ogg"
"SoundScript"	
	{
	"Base" "music/blah.wav"
	"tBeam" "music/sp_a4_tb_intro_tbin.wav"
	"sync_funnel" "1"
	"BounceGel"
		{
		"snd" "music/sp_a3_jump_intro_z1.wav"
		"snd" "music/sp_a3_jump_intro_z1b.wav"
		"snd" "music/sp_a3_jump_intro_z1c.wav"
		}
	....
	}
"Children"
	{
	"SpeedGel" "VALVE_CAUSE_SCIENCE"
	}
}
  • Sample: A short OGG version of the audio file, for preview inside the BEE2. This is saved relative to resources/music_samp/.
  • Soundscript: Specifies the music to play. Each child block is a category of audio to switch in and out. It may either be a single WAV filename, or a block of multiple names (in this case one will be randomly chosen each time it's played). Alternatively a single filename may be provided for the whole block to just define a single Base track.
    • Base: the primary audio track.
    • TBeam: Music used during funnel rides. All other audio tracks fade out when this plays.
    • BounceGel: Music tracks played when the player jumps on Repulsion Gel.
    • SpeedGel: Music played when the player is moving fast horizontally - either from flings, or Propulsion Gel.
    • sync_funnel: Boolean option. If True, the funnel music will be syncrohnised with the base track such that timestamps match in both. This allows matching them to each other. If False (the default), the funnel music will start at a random offset each time.
  • Children: Instead of defining sounds in Soundscript, IDs may be referenced here. These will be used as the default when the other channels are collapsed.
  • Loop_len: MP3 files may also be used for the Base track, but these will not loop. To solve this, this key should be set to the duration of the track (in minute:second format). The music will be automatically restarted after this time period.
  • Instance: If set, this is a special music track of some kind. It can only be used as the base, and this instance is inserted into the map when used. Other channels are disabled. You don't need to provide brushes to seal ents, it's placed in a sealed room.
  • Config: If specified, this config file in the music/ subfolder will be added to vbsp_config.cfg when the music is used as the base track. This does still other channels to be used.
  • Pack: Filename to automatically pack if the music track is included. Referenced WAV files will automatically be packed, so this is not usually needed.

"QuotePack"`

Quote Packs allow defining a set of voice lines which will be selected from dynamically.

Skybox

Skyboxes allow specifying the skybox texture to use, fog colours, and other environmental properties. They also allow specifying options to generate 3D skyboxes and Bottomless Pits.

Elevator

Elevator blocks define videos to use in elevators. Since these can't be packed, there is limited customisation available for this.

Signage (and SignageLegend)

Signage objects allow defining the pictograms that can be selected for the Signage item. The Legend object defines the appearance for the editor model, which is automatically generated to show the exported configuration.

Internal Objects

These are objects used to implement various features, and aren't visible in the BEE2 UI. Most of these types permit duplicates - in this case, the config options are merged together in a random order. This is useful to allow simply including the config data in multiple packages if it's used more than once.

EditorSound

EditorSound blocks allow registering a soundscript so it will be loaded into the editor, so custom sounds can be used for items.

StyleVPK

These define a folder of files which is copied into the DLC3 VPK on export for a style. This overrides the base game, allowing customising the textures in the editor. Since this isn't packable, it's not suited for functionality in the level, but is good to theme the UI.

"StyleVPK"
	{
	"ID" "SOME_VPK"
	"Filename" "the_directory"
	}
  • Filename: The folder inside vpk/ containing the files.

ItemConfig

ItemConfigs attach to a specific item ID, and allow appending additional config options automatically to the original item.

"PackList"

This defines a list of files which can be packed into the map. Deprecated, the compiler is generally able to pack things automatically, and anything it can't can be specified via comp_pack.

BrushTemplate

Templates are a variant of instances, which are pre-processed and may be manually imported directly into the map by the compiler. This provides several benefits - brushes may be retextured automatically based on context, and affect or be affected by other nearby items. In future, these will be automatically detected and not require a definition.

BarrierHole

Defines the shape and appearance for holes that can be cut into glass/grating style barriers. This is a package object so that different barrier frames may append specific appearances for their type.

Add a custom footer
Clone this wiki locally