15.0 Configurable Level¶
15.1 Overview¶
A configurable level is an environment where some elements in it can be changed, such as the color of walls, the placement of a statue or wall, or the texture to display on a mesh. Changing any of these elements is done through the Admin Panel (a web interface) of the server. Below is an example of an AdminPanel for a server running a configurable level.
15.2 Admin Panel¶
The Admin Panel is an administration tool for a server. Within it, there is an "Environment" tab that runs web.alive and displays the current environment on the server. Below it is where the customization controls appear. There are 3 categories of customizations that configurable elements in a level can be grouped under: 1. Floor Plan, 2. Theme, and 3. Custom Color.
15.2.1 Floor Plan¶
This is like the blueprint of a floor in a building. The floor plan shows the layout of rooms, buildings, and openings. A level can be made very large and can contain many rooms. If some of the rooms are not needed, then they can be "turned off" or blocked by changing the floor plan to one that blocks access to it. This is useful for levels that may be too large for the audience it is catering to and allows the administrator to size it appropriately. When a new floor plan is selected, the change occurs immediately and the thumbnail that is displayed for a floor plan will also become the new mini-map. A warning, if there is anyone in a room that disappears, they will get stuck.
15.2.2 Theme¶
Themes can change any element in a level and as its name implies, offers a different style or "look" to the level. This can include changing: colors of walls or furniture, the sky from sunny to rainy, textures from wood to concrete, fountains to billboards, etc...
15.2.3 Custom Color¶
This section allows any individual object in a level to be colored differently. Not every object needs to be "colorable" and the amount of objects offered is up to the level designer.
15.3 Configurable Elements¶
There are 4 types of configurable elements available to the content creator: ConstantColorActor, ChangeableStaticMeshActor, ImageActor, and MaterialSwitchActor. Each one of these is an actor that acts upon an object in the level. These actors are placed in the level the same way as any other type of actor, however they are not visible when the map is running. It is advisable to place these actors together and somewhere off to the side on the map where they will not add confusion to the piles of things already in a map that are visible.
15.3.1 Changing Color using a ConstantColorActor¶
ConstantColorActors are what makes something in the level "colorable". The colorable item (such as a Mesh or a surface) must use a ConstantColor texture or a material that uses a ConstantColor (such as a Combiner) to work. This actor allows an existing ConstantColor texture to change its colors. If a ConstantColor texture is used as a material for more than one mesh or surface on the map, then they will all be affected by the color change. To create one:
1. Select the ConstantColorActor from the actor list
2. Place it in the map
3. Set the AssignedTexture property on it to the ConstantColor texture you wish to be affected
15.3.2 Making Things Disappear/Re-appear using a ChangeableStaticMeshActor¶
Useful for making things like walls, doors, or furniture disappear/re-appear. The actor makes this happen by modifying the bCollideActors and bHidden properties of the object. Normally, StaticMeshes aren't allowed to do this and as its name suggests, they're static so they shouldn't be changing over time. (But this is an exception).
To create one:
1. Select the ChangeableStaticMeshActor from the actor list
2. Place it in the map. A large cube will appear with the default rock bubble texture.
NOTE: To improve bandwidth efficiency, Unreal quantizes the values of vectors and rotators. The X,Y,Z components of vectors are converted to 16-bit signed integers before being sent, thus any fractional values or values out of the range -32768..32767 are lost. The Pitch,Yaw,Roll components of vectors are converted to bytes, of the form (Pitch>>8)&255. Please do not use fractional values for the location or rotation properties. Doing so may result in the changeable static mesh appearing mis-aligned when the environment is in running in client-server mode.
3. Assign a mesh to it
4. Set the bCollideActors and bHidden properties to your appropriate default.
15.3.3 Switching Textures on things using a MaterialSwitchActor¶
Useful for changing the current material in use by a MaterialSwitch.
15.3.4 Changing the Image (.jpg) used in a texture using an ImageActor¶
The actor responsible for Insertions, this is useful for changing the image or .jpg that is currently used by a texture.
See section 7.4 (Insertions) for more information on how to create an ImageActor.
15.4 Making Configurable Elements Available for Customization¶
A file called level.xml is the description of all things that are configurable in your level. This is what ties your configurable map to the Admin Panel. Without it, any configurable elements in your map would go unused. Unfortunately, this file must be constructed by hand and added to your map's project directory. To help you get started however, a sample file is available here (Some knowledge of xml will greatly help).
15.4.1 Level.xml¶
An xml editor is highly recommended when editing this file, but any text editor will do if you're not squeamish to looking at html like tags. There are two main groups or nodes of information: 1. configurableGroups and 2. configurableActors. It's easier to start at the bottom of the file and work your way to the top. <configurableActors> contains a list of every configurable element in your level. In <configurableGroups>, each <configurableGroup> item within it refers to a section of the AdminPanel as described above (1. Floor Plans, 2. Themes, and 3. Custom Color).
15.4.1.1 A Sample <configurableActors> List
<configurableActors>
<actor id="ccAccent1" type="ConstantColorActor" title="Accent Color 1 (EG: Color over doors)"></actor>
<actor id="ccAccent2" type="ConstantColorActor" title="Accent Color 2 (Meeting Room Accents)"></actor>
<actor id="imgLoungeWall" type="ImageActor" title="The Lounge Barrier Wall (Tiling)"></actor>
<actor id="imgCarpet1" type="ImageActor" title="Carpet in Cubicles and Lounge (Tiling)"></actor>
<actor id="meshOfficeFurniture" type="ChangeableStaticMeshActor" title="Meeting Table and Chairs"></actor>
<actor id="meshRoof" type="ChangeableStaticMeshActor" title="Rooftop outside the Window"></actor>
</configurableActors>
In the above example, 7 actors are listed as being configurable in the map. Looking at the first entry:
<actor id="ccAccent1" type="ConstantColorActor" title="Accent Color 1 (EG: Color over doors)"></actor>
id is the actor's tag name as listed in the editor
type is the actor's type and it must be one of: ConstantColorActor, ImageActor, ChangeableStaticMeshActor, or MaterialSwitchActor.
title is a description of the object the actor is affecting and this appears in the Admin Panel's Custom Color panel. Note that only ConstantColorActors appear in the Custom Color panel.
15.4.1.2 A Sample <configurableGroup> list
<configurableGroup id="rooms" title="Floor Plan" description="Select rooms to make available in the environment.">
<option id="roomplan1" caption="Enable all" thumbnail="roomplan1.jpg" description="Extra rooms enabled">
<entry actorRef="WallMeshRooms" value="hide"></entry>
<entry actorRef="WallMeshPortal" value="hide"></entry>
<entry actorRef="minimapswitch" value="minimaproomsyes.png"></entry>
</option>
<option id="roomplan2" caption="Extra rooms enabled" thumbnail="roomplan2.jpg" description="1 room enabled">
<entry actorRef="WallMeshRooms" value="hide"></entry>
<entry actorRef="WallMeshPortal" value="show"></entry>
<entry actorRef="minimapswitch" value="minimaproomsyesteleno.png"></entry>
</option>
</configurableGroup>
In the above example, this configurableGroup has the id of "rooms" and is used to populate the Floor Plan section in the Admin Panel. Within this group, there are 2 options: roomplan1 and roomplan2. Looking at option 1 more closely:
<option id="roomplan1" caption="Enable all" thumbnail="roomplan1.jpg" description="Extra rooms enabled">
id is the name of the first floor plan and will appear under that options thumbnail in the Admin Panel.
caption is a short description of what the first floorplan does
thumbnail is an image of the floorplan that looks like the mini-map.
description is a place to store a note about the floorplan, but it does not appear anywhere.
Within Floorplan1, there are 3 entries within it that list the actors to modify. When this option is selected, it will perform an action against these actors. Each entry describes a new value that actor should change to:
<entry actorRef="WallMeshRooms" value="hide"></entry>
<entry actorRef="WallMeshPortal" value="hide"></entry>
<entry actorRef="minimapswitch" value="minimaproomsyes.png"></entry>
actorRef this is the tag name of the actor as listed in the <configurableActors> list.
value this is the new value that actor should be changed to and is dependent on the type of actor. See the table below for valid values for each actor type.
Valid values for each actor type
Type Eg.Value Description ---- -------- ----------- ConstantColorActor A1B2C3 an RGB hex value for color that sets the "RGB" properties of a ConstantColor texture MaterialSwitchActor 0 a numeric value between 0-4 that sets the "Current" property of a MaterialSwitch texture ChangeableStaticMeshActor hide the string "hide" or "show" that sets the "bCollideActors" and "bHidden" properties of a StaticMesh ImageActor wood.jpg the name of an image file (.jpg) that sets the "filename" property of an Insertion
15.4.2 Configurable Border Color
As of version 3.0, a special ConstantColorActor allows customization of the background border color on the default web.alive web page. Simply add the following entry to the configurableActors section of Level.xml, and the border color will be cusomizable along with the custom colors. No other changes to the map are needed.
<configurableActors>
<actor id="waBorderColor" type="ConstantColorActor" title="Color of Border on Template Web Page"/>
</configurableActors>