Portal 2 Puzzle Maker: editoritems.txt

editoritems.txt is the configuration file which defines the items available in the Puzzle Maker. It is located at Portal 2/portal2_dlc2/scripts/editoritems.txt.

Note:This documentation assumes you have a basic knowledge of Hammer and instances.

Note:Portal 2 must be restarted for changes to this file to take effect.

Todo: Migrate documentation here from the BEE2 wiki page, and finish things which went undocumented there.

Basic Layout

"ItemData"
	{
	"Item" 
		{ ... }
	"Item" 
		{ ... }
	"Renderables"
		{
		"Item"
			{ ... }
		}
	}

editoritems.txt is mainly composed of a large number of Item blocks. These are contained within a top-level ItemData block. Renderables defines the models used for the placement error icon and the connection heart, and should not need to be altered.

Item Format

"Item"
	{
	"Type"		"UNIQUE_ITEM_ID"
	"ItemClass"	"ItemBase"
	"Editor"
		{ ... }
	"Properties"
		{ ... }
	"Exporting"
		{ ... }
	}

Type

The ID for this item, which must be unique. Must be present.

ItemClass

Set to predefined values, providing item-specific behaviors. See below for a list of valid classes and their functionality. This property is optional. The default class is ItemBase, and is used if no class is specified.

Following the item type and class, each Item block is split into 3 sections:

• Editor defines how the item should appear and behave within the Puzzlemaker itself.
• Properties defines what properties should appear in the item's context menu, and be exported to the instance as $fixup variables.
• Exporting defines how the item should be exported into compiled maps, along with the item's collisions and embed space in the editor.

Editor

The Editor block contains one or more SubTypes. Most items will only need one of these, but more can be used to give the item multiple variants if necessary.

"Editor"
{
	"SubTypeProperty"		"ButtonType"
	"SubType"
	{
		"Name"			"Item Name"
		"Model"
		{
			"ModelName"	"model_name.3ds"
			"TextureName"	"texture_name.png"
		}
		"Palette"
		{
			"Tooltip"	"ITEM NAME"
			"Image"		"palette/icon.png"
			"Position"	"0 0 0"
		}
		"Sounds"
		{
			"SOUND_CREATED"			"P2Editor.PlaceOther"
			"SOUND_EDITING_ACTIVATE"	"P2Editor.ExpandOther"
			"SOUND_EDITING_DEACTIVATE"	"P2Editor.CollapseOther"
			"SOUND_DELETED"			"P2Editor.RemoveOther"
		}
	}
	"MovementHandle"	"HANDLE_NONE"
	"DesiredFacing"		"DESIRES_UP"
	"InvalidSurface"	"CEILING WALL"
	"CanAnchorOnBarriers"	"1"
	"CanAnchorOnGoo"	"1"
}

SubTypeProperty

If this item has multiple SubTypes, the property specified here will be used to switch between them. Valve's items only use the "type" dropdowns for this, but any property can be set here, including the pedestal button timer widget.

Name

The name displayed for this item in the Remove Connections dropdown. Valve's items set this to a localization token, but this is not necessary for custom items unless you intend to translate the name. See Tooltip for the name displayed in the palette.

ModelName

The name of the model to display in the editor, with the extension .3ds. This is not the name of an actual file, but is used as a base; the visible model is loaded from a .mdl file relative to models/props_map_editor, and the selection mesh is loaded from a .3ds file relative to models/puzzlemaker, with selection_ added at the start of the path.

Bug:selection_ is added at the start of the path, rather than the filename. So if ModelName is set to subfolder/model.3ds, the selection mesh would be loaded from selection_subfolder/model.3ds, not subfolder/selection_model.3ds  [todo tested in ?]

Note:Some item classes require multiple models. These are set by having multiple Model blocks, and can be duplicates. The required models for each class are listed below.

Warning:If the required number of models are not specified, the game will crash upon placing the item, regardless of which model would actually be used.

TextureName

Does not appear to be used, and can be omitted without causing issues. In all of Valve's items, this contains a PNG image to be applied to the model. The actual used textures are materials and their paths are specified within the model itself, so it's unknown what this was used for.

Tooltip

The name displayed for this item when mousing over it in the palette. Generally written in all uppercase, though this is not required. Valve's items set this to a localization token, but this is not necessary for custom items unless you intend to translate the name.

Image

The name of the icon to display in the palette, relative to materials/models/props_map_editor. The texture itself needs to be a VTF, although it is specified here with a .png extension. Note that a VMT is not needed for palette icons, unless you also intend to use them elsewhere (such as on a model).

Position

The item's position on the palette. 0 0 0 is the top-left corner, and 3 7 0 is the bottom-right.

Sounds

The names of soundscripts to play when performing certain actions on the item.

• SOUND_CREATED: Played when the item is first placed on a surface.
• SOUND_EDITING_ACTIVATE: Played when the item's context menu is opened.
• SOUND_EDITING_DEACTIVATE: Played when the item's context menu is closed.
• SOUND_DELETED: Played when the item is deleted.
• SOUND_SELECTED: Played when the item is selected. Not used in any of Valve's items, but exists in the code.
  Todo: Does this work?
• SOUND_DESELECTED: Played when the item is deselected. Not used in any of Valve's items, but exists in the code.
  Todo: Does this work?

Animations

Animations to play when performing actions on this item. Note that this is not needed for the standard explode/collapse animations, which will work without this provided they exist in the model.

• ANIM_IDLE: Default animation/pose, when the properties menu is closed. For cubes, this is only used when the dropper is disabled.
• ANIM_EDITING_ACTIVATE: Played when the properties menu is opened. If multiple subtypes are present, the new model switches to the last frame of this animation instantly.
• ANIM_EDITING_DEACTIVATE: Played when the properties menu is closed.

Specific to ItemCubeDropper:

• ANIM_REAPPEAR: Played when the dropper is re-enabled. The first frame should start the dropper far above the origin.
• ANIM_DISAPPEAR: Played when the dropper is disabled or deleted. The last frame should end with the dropper far above the origin.

Specific to ItemCube:

• ANIM_GROUND_TO_FALLING_EDITING: Played when the dropper is re-enabled, and the properties menu is open.
• ANIM_FALLING_TO_GROUND_EDITING: Played when the dropper is disabled, and the properties menu is open.
• ANIM_GROUND_TO_FALLING: Played when the dropper is enabled, and the properties menu is closed. This only occurs when the item is first placed.
• ANIM_FALLING_TO_GROUND: Played when the dropper is deleted while the properties menu is closed.
• ANIM_FALLING_EDITING_DEACTIVATE: Played when the properties menu is closed, and the dropper is enabled.
• ANIM_FALLING_EDITING_ACTIVATE: Played when the properties menu is opened, and the dropper is enabled.
• ANIM_FALLING_IDLE: Idle animation used when the dropper is enabled.

MovementHandle

Sets the type of rotation the item will have. The default is HANDLE_NONE. The -x side of the instance is generally the "front" of the item.

• HANDLE_NONE: Does not give a handle. The item can still be rotated in 4 directions by DesiredFacing, or by moving it around the corner of a chamber.
• HANDLE_4_DIRECTIONS: Gives a quarter-circle handle to allow pointing in 4 directions.
• HANDLE_5_POSITIONS: Allows center-positioning, and 4 side positions. This is done by rotating the item, and switching between two different items when centered/offset. The item types to swap between are hard-coded, so this handle only works with ITEM_LASER_CATCHER, ITEM_LASER_RELAY and ITEM_LASER_EMITTER (_CENTER / _OFFSET).
• HANDLE_6_POSITIONS: Allows centering in two orientations, and offset on the 4 sides. The instance should be centered, with the sides in the y axis. When offset, the +x side faces toward the center of the voxel.
  Todo: Does the bug with CanAnchorOnBarriers also affect this handle?
• HANDLE_8_POSITIONS: Allows placement on the inner and outer quarter tiles in each direction. Instances should be centered 32 units wide. The -x side is placed flush with the voxel border.
  Bug:Combining this with CanAnchorOnBarriers will cause the item to reset to the center of the voxel whenever the chamber geometry is changed.  [todo tested in ?]
• HANDLE_36_DIRECTIONS: Allows rotation on the floor in increments of 10°.
  Bug:This handle does not function properly on wall- or ceiling-placed items. InvalidSurface should be used.  [todo tested in ?]
• HANDLE_CATAPULT: Special rotation handle used for Faith Plate items and their targets.
  Todo: Figure out what this actually does, it's probably related to the plate/target link.

DesiredFacing

Allows defaulting to a specific orientation on walls:

• DESIRES_ANYTHING: default, performing no rotation.
• DESIRES_UP: Rotate so +x is facing upright, and the rotation handle points down.
• DESIRES_DOWN: Rotate so -x is facing upright, and the rotation handle points up.
• DESIRES_HORIZONTAL: Rotate so the y axis is vertical. Which side is upright varies depending on which wall it is placed on.

InvalidSurface

Allows prohibiting placement of the item on a surface. Defaults to none, but can be set to any combination of WALLS, FLOOR, and CEILING to disallow placement on that surface.

CanAnchorOnGoo

If enabled, the top surface of goo pits will be treated as a surface to attach to.

CanAnchorOnBarriers

If enabled, several surfaces will be treated as attachment points: the side of Glass/Grating, tops of 90° Angled/Glass Panels, the top of Track Platforms, and the surface of Piston Platforms. Eligibility for placement is defined by the relevant item classes (ItemBarrier, ItemAngledPanel, ItemRailLift and ItemPistonPlatform).

Todo: Is this based on item classes or item types?

Bug:Combining this with HANDLE_8_POSITIONS will cause the item to reset to the center of the voxel whenever the chamber geometry is changed.  [todo tested in ?]

Properties

"Properties"
	{
		"PropertyName"
		{
			"DefaultValue"	"0"
			"Index"		"1"
		}
		"StartEnabled"
		{
			"DefaultValue"	"1"
			"Index"		"2"
		}
		. . .
	}

PropertyName

Replace with the name of the property, such as StartEnabled. Property names can be found below.

DefaultValue

The default setting for this property.

Index

This is usually numbered consecutively, starting with 1.

Todo: Document what this actually does.

Unclassed Properties

Todo: Document

Specialized Properties

Todo: Document

Exporting

Todo: Document

Offset

The offset applied to instances. This should generally always be set to 64 64 64, so the instance rotates around the center of the voxel.

Item Classes

Todo: Document