Using the Panel Editor

From C4 Engine Wiki

The C4 Engine contains a dedicated editor for creating interactive in-game interface panels (or just panels for short). Level designers may create panels, add various interface elements to them, assign different animations to those elements, and attach scripts to interactive items.

The image to the right shows the Panel Editor. An interface panel can be created in a scene using the Panel Effect tool in the Effects page in the World Editor. The contents of the panel are edited by following these steps:

1. In the World Editor, select the panel effect whose contents you want to edit.
2. Choose Get Info from the Node menu or just press Ctrl-I.
3. Click on the Controller tab in the Get Info dialog.
4. Click on the Edit Panel button that appears to open the Panel Editor.

Contents 1 Creating a New Panel 2 Editing a Panel 2.1 Common Settings 2.2 Image Item Settings 2.3 Text Box Item Settings 2.4 Camera Item Settings 2.5 Movie Item Settings 3 Panel Editor Tools 4 Menu Commands 5 Mutators 6 Interactivity

Creating a New Panel

A panel is drawn in the World Editor using the Panel Effect tool (shown to the right) in the Effects page. The Panel Effect tool draws a rectangular region representing the boundary of the panel. When a panel is first created, it automatically has a Panel Controller assigned to it that can be accessed under the Controller pane in the Node Info dialog.

A panel possesses both its physical size in the world, as drawn with the Panel Effect tool, and an internal interface resolution. The resolution is adjusted in the properties for the Panel Controller. The interface resolution determines how big the virtual screen is on which items will be placed with the Panel Editor. Whatever resolution is chosen, the entire panel is fit precisely into the physical dimensions determined by the rectangle drawn in the World Editor. Thus, it's usually desirable to match the aspect ratios of both the panel's physical size and its interface resolution to avoid stretching the contents of the panel.

Under the Panel pane in the Get Info dialog, there are three check boxes that affect how the panel is rendered.

• The “Apply depth offset” flag causes the panel to be rendered with a small depth offset forward. This avoids z-fighting artifacts that could otherwise appear if a panel was drawn in the same plane as background geometry.
• The “Render two-sided” flag causes the panel to be rendered regardless of on which side of the panel's plane the camera currently is. This lets the panel be seen from the back if it's drawn on a transparent surface or floating in mid-air.
• The “Render with fog” flag allows fog to be rendered over a panel. This must be explicitly enabled in order for a panel to be rendered in a fogged environment.

Editing a Panel

The Panel Editor is opened by clicking on the Edit Panel button under the Controller pane of the Node Info dialog.

There are three tools in the upper-left corner of the Panel Editor that are used to draw new panel items. One draws image items, another draws text box items, and the third draws camera items. When a new image item is drawn, the texture selected from the list on the left side of the editor is initially applied to it. (The textures shown in the palette are those in any Data/*/panel/ directory.)

When one or more panel items are selected, their properties can be edited on the right side of the window. Different properties are shown depending on the types of the selected items, but all items have an identifier, a color, and two flags indicating whether the item is initially disabled or hidden. Settings that differ among multiple selected items are displayed in an indeterminate state until they are modified.

Common Settings

• The “Item identifier” is a four-character code used to identify panel items from a script and can be left blank for items that will not be referenced. This identifier does not need to be unique. When a script operates on panel items, it affects all panel items (in a single panel) having the same item identifier.

• The “Item color” is the color with which a texture is multiplied for an image item or the color of the text in a text box item.

• The “Disabled” check box indicates whether the item is initially interactive. For an item to be interactive, it must also have a script attached to it (see below).

• The “Hidden” check box indicates whether the item is initially visible.

Image Item Settings

• The “Texture image” field specifies the texture resource to use in the image item. It can be changed by entering a new filename or by clicking the Choose button.

• The “X scale and “Y scale fields specify the factors by which the texture coordinates at the corners of the image item are multiplied. Larger values cause the texture to appear to shrink, and smaller values magnify the texture.

• The “X offset and “Y offset fields specify the amounts added to the texture coordinates at the corners of the image item. A value of 1.0 represents the full texture size in either direction.

Text Box Item Settings

• The “Text” field contains the text that is displayed in the text box. Text boxes are bottomless—if more text is entered than can fit in the box, then it flows out through the bottom. However, only the interior of the text box is considered for interactivity.

• The “Font” menu allows a font to be chosen for the text box. For best results, the font should be one that was imported with mipmaps so that aliasing doesn't occur when the panel is viewed from a distance. The Block font distributed with the engine has mipmaps.

• The “Alignment” menu specifies whether text is horizontally aligned left, center, or right within the text box.

• The “Text scale” field allows you to change the scale of the text. Fonts will usually look okay when scaled down, but fonts scaled up too much may begin to look pixelated.

• The “Extra leading” field controls have much space is added between lines of text. This can be negative, if desired, to move lines closer together.

• The “Display as single line” check box causes the text to be displayed on a single line. Any text that extends outside the item's bounding box is clipped.

Camera Item Settings

A camera item is used to display the rendered image from a camera somewhere else in the world. It has a single setting, called “Camera connector”, that specifies the identifier for a connector attached to the panel effect that links to the camera node that will supply the image. (Such a connector can be created under the Connectors pane of the Node Info dialog.)

Movie Item Settings

If the Movies plugin is installed, then a panel item for showing movies is available.

• The “Movie name” field contains the resource name of the movie (including extension) or a URL to a movie stored on a remote server.

• The “Movie name is a URL” check box should be checked if the movie name represents the location of a remote movie.

• The “Movie is initially playing” check box determines whether the movie is playing when the world is loaded.

• The “Movie is looping” check box determines whether the movie loops when it reaches the end.

Panel Editor Tools

There are eight tool buttons at the bottom of the Panel Editor window, and they have the following uses. In addition to clicking on the tool button, some of these tools can also be selected by pressing the number key shown in the table. (The shortcuts were chosen to be the same as the corresponding tools in the World Editor.)

Icon	Shortcut	Function
	1	Select. Selects an item. This tool can be used to safely select items without the possibility of accidentally moving them.
	2	Move. Selects and moves items around. Holding down the Shift key while moving constrains the movement to a single axis.
	3	Rotate. Selects and rotates an item. Handles appear on selected items. Dragging a handle rotates the selected items. Holding down the Shift key while rotating snaps the angle to 45 degree increments.
	4	Resize. Selects and resizes items. Handles appear on selected items. Dragging a handle resizes the selected items. Holding down the Shift key while resizing constrains the proportional width and height.
		Texture Offset. Offsets the texture within the selected items.
		Texture Scale. Scales the texture within the selected items.
	6	Scroll. Pans the panel viewport. Holding down the Alt key (Option on the Mac) temporarily selects the pan tool.
	7	Zoom Tool. Scales the panel viewport. Dragging vertically with this tool zooms in and out of a viewport. Using the mouse wheel with any other tool also zooms.

There are also two toggle buttons for grid settings at the bottom of the window.

Icon	Shortcut	Function
		Toggle Gridlines. Shows or hides the grid line display.
		Toggle Snap to Grid. Turns grid snapping on or off.

The color of the gridlines is stored in the $panelGridColor variable.

Menu Commands

In addition to a standard Edit menu, the Panel menu appears in the menu bar when the Panel Editor is open. Each command in the Panel menu is described in the following table.

Mutator	Description
Bring to Front	Brings the selected items to the front so that they are rendered last.
Bring Forward	Moves the selected items forward ahead of the next item that would be rendered.
Send Backward	Moves the selected items backward behind the previous item that would be rendered.
Send to Back	Sends the selected items to the back so that they are rendered first.
Hide Selection	Hides the selected items.
Unhide All	Shows all items in the panel.
Lock Selection	Locks the selected items so that they can no longer be selected.
Unlock All	Unlocks all items in the panel.
Reset Rotation	Removes any rotation from the selected items.
Reset Texcoords	Resets the texture coordinates for selected image items to the default values.
Replace Texture	Replaces the textures for selected image items with the currently selected texture image.
Auto-scale Texture	Scales the texture coordinates of selected image items so that the image's aspect ratio is 1:1.
Edit Script	Opens the script editor for the selected item. This is equivalent to clicking the Edit Script button at the bottom of the editor.
Delete Script	Removes the script from the selected items. (This is undoable.)

Mutators

Any panel item may have a list of mutators applied to it. Mutators dynamically change the appearance of a panel item in some way to achieve animation effects. The following table describes the mutators that are built into the engine. Applications may define custom mutators by defining subclasses of the Mutator class.

Mutator	Description
Fade	Causes the color of a panel item to smoothly change to a new value, and then stops.
Pulsate	Varies the color of a panel item back and forth between its original value and another color specified by the mutator. The interpolation can be based on a square wave (for blinking), a triangle wave, or a sine wave.
Randomize	Continually assigns a random offset to the texture coordinates of an image item. This can be useful for producing effects like television static with a noise texture.
Rotate	Rotates the texture coordinates of an image item. A positive speed rotates counterclockwise, and a negative speed rotates clockwise.
Scale	Scales an image item to a given multiple of its original size, and then stops. The texture coordinates can be fixed so that the image is magnified (or shrunk), or the texture coordinates can be scaled to achieve wipe effects.
Scroll	Continually scrolls the texture coordinates of an image item.
Ticker	Scrolls text in a text item like a stock ticker. The text must be displayed as a single line.
Animate	Plays a sequence of frames from a texture map.

Each mutator can have an identifier assigned to it in the form of a four-character code. As with panel items, these identifiers do not have to be unique and are used to identify specific mutators from a script.

Interactivity

A panel effect can be made interactive by assigning the Interaction property to it under the Properties pane of the Node Info dialog. An interactive panel can display a cursor on top of the panel items while the user is engaged with the panel effect. The cursor's texture image is specified in the panel controller's settings in the Get Info dialog.

A panel item within an interactive panel becomes “clickable” when it has a script attached to it. A script is attached to a panel item by selecting the item and clicking the Edit Script button at the bottom of the Panel Editor. This opens the same script editor used by the script controller. The script can access functions of the panel controller itself, or it can access any nodes linked to the panel effect node through connectors.