Skip to content

Package Format

Jump to bottom Edit New page
Spencer Brown edited this page Jun 4, 2022 · 6 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
  - resources
    - BEE2
    - instances
    - materials
    - music_samp
    - models
    - sound
    - scripts
  - 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 item from another package. The ID should match another item (if no match is found, the definition is ignored). The configuration is merged with the original item 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.

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"

These define styles which can be chosen. This is generally paired with Item overrides, to specify the style variants for items in this specific style.

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.

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.

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.

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.

Add a custom footer
Clone this wiki locally