items tutorial
This tutorial will demonstrate how to create a custom item for the Portal 2 editor, using BEEmod. You will need to be somewhat familar with various parts of Source Engine modding, since they will not be repeated here - Hammer mapmaking, VTF texture creation, and making/compiling models.
In this tutorial, we will be building a "furniture" item, which allows users to place a chair into their test chambers.
In BEEmod, custom content is organised into zip files called "packages". This allows new content to be easily copied in, and loaded/unloaded into the game autmoatically. For distribution it is contained inside a zip file, but for ease of development a simple folder can also be used. To create one, add a folder or zip file into the packages/ folder and create a file called info.txt inside it. This file defines all the kinds of objects made available by the package. For a single item, it is fairly simple:
"ID" "TUT_ITEM"
"Name" "Tutorial Item - Furniture"
"Desc" "Adds fancy furniture for your Test Chambers!"
"Item"
{
"ID" "ITEM_TUT_FURNITURE"
"Version"
{
"Styles"
{
"BEE2_CLEAN" "furniture_clean"
}
}
}The 3 lines at the top describe the entire package. The ID here must be unique - it's a good idea to put your name or something similar in it to make sure someone else doesn't repeat the name. The name and description here shows up in the "enable/disable packages" window in the application. Below this, the "Item" block indicates that this package contains a single item. Adding more of these blocks after would add other items as well. Similar to the package as a whole, this also requires a unique ID. Finally, the folder furniture_clean is specified to be used for the BEE2_CLEAN style (the ID for normal Clean). You'll need to create an items/ folder inside your package, and create a furniture_clean folder. In there two files will be needed to control the appearance and properties of the item - editoritems.txt, properties.txt, and vbsp_config.cfg. The latter is optional.
In addition to info.txt, all packages can have a resources/ folder which contains all the content used by the game or BEEmod. When exported, this is automatically copied to the right place as needed. As a developer you'll want to turn on "Preserve Game directory" in the BEE2 options, to ensure that any changes you make to the game folders aren't overwritten. The following subfolders are available:
-
instances: The contents are copied tosdk_content/maps/instances/BEE2/. -
BEE2/: This folder is used to hold PNG images shown inside the BEE2 application itself. -
materials,models,scripts,sound: These are mounted into the game likeportal2/,portal2_dlc1,portal2_dlc2etc. However, you cannot override existing files - workshop maps can't do this anyway.
After making a package, the first thing that needs to be done is to create the instance of the item in Hammer. Instances are maps like any other, but only containing a small part of the level. They can then be inserted in the overall level using a func_instance entity. The puzzlemaker uses instances extensively to implement every item. The editor uses a 128-unit grid, with the origin (the 3-axis shape at the center of the map file) in the center of the square. The place the item is attached to is below this, so 64 units from the center point. Usually, the "front" of the item is pointed in the opposite direction to the red line - left on the top view.
The first and most important config file for items is the editoritems.txt file. This specifies everything about the behaviour of the item inside the editor, and how it is exported into the final map. The format is the same as the original file (in portal2_dlc2/scripts/editoritems.txt) which is altered each time BEE2 exports. The files are somewhat long, so it's best to copy an existing file as a template and proceed from there:
"Item"
{
"Type" "ITEM_TUT_FURNITURE"
"ItemClass" "ItemBase"
"Editor"
{
"SubType"
{
"Name" "Furniture"
"Model"
{
"ModelName" "turret.3ds"
}
"Palette"
{
"Tooltip" "FURNITURE"
"Image" "palette/portal_button.png"
}
}
"MovementHandle" "HANDLE_4_DIRECTIONS"
"InvalidSurface" "WALL CEILING"
}
"Properties"
{
}
"Exporting"
{
"Instances"
{
"0"
{
"Name" "instances/BEE2/clean/items/tutorial/chair.vmf"
"EntityCount" "1"
"BrushCount" "1"
"BrushSideCount" "6"
}
}
"TargetName" "furn"
"Offset" "64 64 64"
"OccupiedVoxels"
{
"Voxel"
{
"Pos" "0 0 0"
"Surface"
{
"Normal" "0 0 1"
}
}
}
}
}There are a number of things here. Firstly, Type should be the same as the item's ID. This particular item will use the base "class". Every item in the default palette aside from the observation room has a unique "item class", which produces the special behaviour like items being resizeable. To use these behaviours custom items will need to replicate the same configurations.
A single SubType is also used - these are things like Weighted/Cube/Sphere buttons. Every item has at least one, with the number being controlled by which item class and "type" property is used. Inside the name and editor model(s) are defined for the subtype. The name appears in the "remove connections" dialog, and the editor model is used to control the appearance. Optionally, the Palette section can be used to allow this subtype to appear on the BEE2 items list and allow it to be put on the palette. Here you need to define the uppercase tooltip, and the icon image to use.
Despite the extension, this is in fact a VTF icon, which is expected to be somewhere relative to materials/models/props_map_editor/. BEE2's icons are generally in palette/BEE2/<style>/ on top of that, to keep them organised. No VMT is required. For creation of these, any normal image editor works. The background is #E5E8E9, and the images are usually 256x256.
MovementHandle and InvalidSurface are two optional properties used here. These respectively enable the 4-way directional rotation widget, and disallow putting the chair on the walls or ceiling.
Instances specifies the 1 instance used for this item, here in the expected place for items. To ensure the instance doesn't conflict with another package, it's important to include your name or another unique folder. The counts here are used for the puzzlemaker_enable_budget_bar feature, and are optional.
OccupiedVoxels effectively defines the collision for the item. Here it's fairly simple - one side of the voxel 0 0 0, on the floor. You can also define occupation for an entire voxel, or ¼ voxel sections.
Editor models are normal animated models, with no collisions. They are oriented/positioned exactly the same as the instance itself, so matching that is fairly easy. To accomplish the animations while the properties menu is open, 3 animations are required: idle, explode_out, explode_in. The names are unimportant, but they need to be specified in the QC file in that order. The model itself needs to be placed in models/props_map_editor/, or a subfolder.
There additionally needs to be a "selection model" file - this is a .3ds mesh, used to determine whether the mouse is hovering over the item. It's a model similar to a collision model (Blender can export one), but it's scaled down by 128 (0.0078125) so that a block is 1 unit wide. It also doesn't have to be convex or even "water-tight" - holes can be present to make the item selectable only from one direction or to simplify the mesh. These need to be named models/puzzlemaker/selection_modelname.3ds, matching the name of the associated editor model. If the model is in a subfolder, selection_ needs to be added at the start of the subfolder's name rather than the file - so puzzlemaker/selection_subfolder/modelname.3ds, not puzzlemaker/subfolder/selection_modelname.3ds.
The other required file in the item's folder is properties.txt. This holds various options intended for BEE2 itself:
"Properties"
{
"Authors" "Example Dude, Helper Person"
"Tags" "Tutorial;Geometry;Comfy"
"Description" "A nice set of table and chairs for your Test Subjects to relax in.
* Padded seat provided free of charge!
"
"InfoURL" "http://www.example.com/tutorial_item.html"
"Ent_count" "1"
"Icon"
{
"0" "clean/tutorial/chair.png"
}
}-
Authors: Specifies who made this item to show in the right-click menu. Also implicitly acts as a set of tags. -
Tags: Each of these phrases can be used to filter items with the 'tags' pane in the application. -
Description: Fills the box in the right-click menu. Multiple lines of text can be entered, and most Markdown syntax can be used to apply special styles.