Workshop Modding
Information below might not be relevant in the latest game version.
Contents
Editing and Creating your Own Room Configuration Files
The following is a detailed guide to modifying rooms for a KAG server.
The first step is to determine which gamemode file to edit, because room files are directly linked to a specific gamemode. Basically, if you add custom shops to a vanilla CTF room file, you may need to create a new gamemode.cfg and a new room.cfg.
For this tutorial, we will be using the room file called CTF_Room.cfg.
The files are found in your Base\Entities\Rooms folder.
The default room configuration file for Capture the Flag mode looks like this:
# Workshop config file
# $ string
# @ array
# sprite
$sprite_factory = room_sprite
$sprite_texture = Entities/Rooms/Sprites/EmptyRoom.png
s32_sprite_frame_width = 24
s32_sprite_frame_height = 24
$sprite_sound_death_hit =
$sprite_sound_flesh_hit = Sounds/pick_wall?.ogg
$sprite_sound_die = Sounds/destroy_wall.ogg
$sprite_sound_spawn = Entities/Rooms/Sounds/ConstructShort.ogg
$sprite_sound_gib = Entities/Rooms/Sounds/DestroyRoom.ogg
$sprite_sound_emit =
$sprite_gibs_start = *start*
$gib_type = static_particle
$gib_file = Entities/Rooms/Sprites/RoomGibs.png
u8_gib_count = 9 #number of gibs
u8_gib_style = 0 #column
u8_frame_width = 8;
u8_frame_height = 8;
@u8_gib_frame = 1; 2; 3; 4; 5; 6; 7; #row
$gib_collide_sound = Sounds/rock_hit?.ogg
f32_gib_mass = 2.5
u8_gib_emit = 255 #nothing
f32_velocity = 12.0
f32_offset_x = 0.0
f32_offset_y = 0.0
$sprite_gibs_end = *end*
f32_blood_multiplier = 8.0
clr_blood_color = 255; 50; 40; 30
$sprite_animation_start = *start*
# default
$sprite_animation_default_name = default
u16_sprite_animation_default_time = 1
u8_sprite_animation_default_loop = 0
@u16_sprite_animation_default_frames = 0;
$sprite_animation_end = *end*
# light
f32_light_radius = 50.0
clr_light_color = 255; 255; 240; 171
1_light_default_on = 0
# room
$sprite_sound_build = Entities/Rooms/Sounds/Construct.ogg
# ball
$ball_factory = room_ball
f32_ball_width = 24.0
f32_ball_height = 24.0
f32_ball_radius = 12.0
f32_ball_max_upspeed = 0.0
f32_ball_max_fallspeed = 0.0
f32_ball_max_airspeed = 0.0
f32_ball_max_groundspeed = 0.0
f32_ball_max_actionspeed = 0.0
f32_ball_gravity = 0.0
f32_ball_ground_slide = 0.0
f32_ball_wall_slide = 0.0
f32_ball_ladder_slide = 0.0
f32_ball_ground_bounce = 0.0
f32_ball_wall_bounce = 0.0
1_ball_opens_doors = 0
1_ball_opens_bridges = 0
f32_ball_hit_momentum = 0.0
# unused
$movement_factory =
$weapon_factory =
$brain_factory =
$attachment_factory =
# general
$name =
f32_health = 3.0
f32 gib_health = -2.5
$help_text = Hold $KEY7$ and\nselect workshop\nto build
u8_default_room = 0
# room syntax - room name; room level (0 menu - 1... upgrade); room sprite; room help text; room items/functions, item2, item3 ...; costs , , , (g gold, s stone, w wood, c coins, l level, u upgrades_from, r requires_roomname- none) ...
@$rooms = BOMB WORKSHOP; Entities/Rooms/Sprites/BombShop.png; $KEY7$ to buy bombs; bomb; w50;
QUARTERS; Entities/Rooms/Sprites/Quarters.png; Wait inside to heal; heal; w50;
ARROW WORKSHOP; Entities/Rooms/Sprites/ArrowShop.png; $KEY7$ to make arrow; arrow; w50;
SIEGE WORKSHOP; Entities/Rooms/Sprites/SiegeShop.png; $KEY7$ to build\ncatapult or outpost; catapult, outpost; w50, g30;
;
# room_function syntax - function name; function actor name; function config file; function icon; function make sound; function icon frame; function icon frame size; function help text; costs , , , (g gold, s stone, w wood, c coins - none) ...
@$room_functions = bomb; -; -; Entities/Items/Sprites/MaterialStacks.png; Entities/Rooms/Sounds/BombMake.ogg; 12; 16; Bomb costs 20 coins; c20;
arrow; -; -; Entities/Items/Sprites/MaterialStacks.png; Entities/Rooms/Sounds/ArrowsMake.ogg; 10; 16; Arrow cost 1 coin; c*10;
catapult; -; -; Sprites/catapult.png; d; 0; 32; Construct a Catapult; w120, c20;
outpost; -; -; Sprites/outpost1.png; d; 0; 32; Construct an Outpost; w120, c50;
heal; -; -; -; Sounds/heart.ogg; 0; 0; Healing 2 coins per 1/2 heart; c2;
;
# - nothing
# - in room_functions as texture = don't add to menu - collide function
# d default build sound
# c*10 - buy as much as possible, max 10,
Holy crap! That's a lot! Don't worry, we'll break it down piece by piece starting with an introduction to commenting.
Introduction to Comments
# Workshop config file
# $ string
# @ array
The first three lines of code are comments. They are preceded by a #. You will see these comments throughout KAG's cfg files to designate section changes and to provide helpful information. Anything on a line that is placed after a # will not be read by the game engine and therefore will not affect your workshops / gamemodes / etc.
In CTF_Room.cfg, the first line is used to remind you which file you are working in, in this case it is a workshop file. The next two lines let you know that the $ symbol designates a string and the @ symbol designates an array. You shouldn't have to worry about that. Now that you know how comments work, consider adding some in your code to remind yourself of any changes that you've made or to add information about what a line does. Now onto editing the default room!
The Default Room
The following code is what we'll be using to edit our default room (the workshop that is created when you join nine workshop blocks in a square):
# sprite
$sprite_factory = room_sprite
$sprite_texture = Entities/Rooms/Sprites/EmptyRoom.png
s32_sprite_frame_width = 24
s32_sprite_frame_height = 24
$sprite_sound_death_hit =
$sprite_sound_flesh_hit = Sounds/pick_wall?.ogg
$sprite_sound_die = Sounds/destroy_wall.ogg
$sprite_sound_spawn = Entities/Rooms/Sounds/ConstructShort.ogg
$sprite_sound_gib = Entities/Rooms/Sounds/DestroyRoom.ogg
$sprite_sound_emit =
Do not change the sprite factory. We are creating a room sprite, so that is what we want.
You may want to change the sprite texture. This is the texture that appears when you add the ninth workshop tile. You can edit the path to a different png file if you wish. The next two lines ask you the size of the sprite. Workshops are 24 x 24 pixels, so we'll leave that be as it is. For the six sounds, you can leave death_hit and emit blank. flesh_hit changes the sound when the workshop is damaged, die and gib are the sounds that play when the shop is destroyed, and spawn is what you hear when you place the final workshop tile. You could even leave some sounds blank if you don't want a sound to play, this creates a great atmosphere for Day/Night servers when you can't hear attack sounds on workshops during the night!
We are now going to skip to the most important section for workshop modding. This is contained directly under the #general note.
Workshop Modding and the Selection Wheel
Here is the code that we will be editing:
# general
$name =
f32_health = 3.0
f32 gib_health = -2.5
$help_text = Hold $KEY7$ and\nselect workshop\nto build
u8_default_room = 0
# room syntax - room name; room level (0 menu - 1... upgrade); room sprite; room help text; room items/functions, item2, item3 ...; costs , , , (g gold, s stone, w wood, c coins, l level, u upgrades_from, r requires_roomname- none) ...
@$rooms = BOMB WORKSHOP; Entities/Rooms/Sprites/BombShop.png; $KEY7$ to buy bombs; bomb; w50;
QUARTERS; Entities/Rooms/Sprites/Quarters.png; Wait inside to heal; heal; w50;
ARROW WORKSHOP; Entities/Rooms/Sprites/ArrowShop.png; $KEY7$ to make arrow; arrow; w50;
SIEGE WORKSHOP; Entities/Rooms/Sprites/SiegeShop.png; $KEY7$ to build\ncatapult or outpost; catapult, outpost; w50, g30;
;
In the first small section starting with $name, you may want to edit f32_health and $help_text. The default for workshop health is 3.0, which is actually equivalent to 6 hearts (A knight can destroy a shop in six jabs). The help text is displayed in-game when you first create the empty workshop. You can change this text to display whatever you like, using \n to designate a line-break.
You can leave u8_default_room as it is. If you want more information about what this can do, look here
Now onto workshop syntax!
To edit your room syntax, we'll be following this helpful comment:
# room syntax - room name; room level (0 menu - 1... upgrade); room sprite; room help text; room items/functions, item2, item3 ...; costs , , , (g gold, s stone, w wood, c coins, l level, u upgrades_from, r requires_roomname- none) ...
This is basically what you'll be editing to make your new rooms, or to edit your existing ones. To make things simpler, you can use this as a template to create rooms:
ROOM_NAME; Entities/Rooms/Sprites/EDIT_THIS.png; HELP_TEXT; ROOM_ITEMS/FUNCTIONS, SEPARATED_BY_COMMAS; COSTS, SEPARATED_BYCOMMAS;
Let's consider each block one by one.
ROOM_NAME; designates the name that will appear in the middle of the selection wheel when you attempt to build a workshop.
Entities/Rooms/Sprites/EDIT_THIS.png; is the path to the room image file that you want to use. This image file can be in another folder other than the rooms folder, but that is where the room textures are located.
HELP_TEXT; is the text that appears when you stand next to the shop once you've built it. For example, the quarters displays "Wait inside to heal" if you stand close to it.
ROOM_ITEMS/FUNCTIONS, SEPARATED_BY_COMMAS; is the list of items and functions that display in the room's item/function wheel. Any text in this block must be exactly as is shown in the room_function section, which will be explained later (starts with #room_function syntax .....).
To make your own custom shops, separate the items and/or functions that you want by commas, and they will appear clockwise in order around the center of your selection wheel. (Special Note: If you wish to make a function that upgrades one shop to another, add a function called upgrade ROOM_NAME, where ROOM_NAME is the name of the room you wish to upgrade to.)
COSTS, SEPARATED_BY_COMMAS; is the last block for the workshop and determines its building cost. There are six main costs for building shops: gold, stone, wood, coins, upgrading, and requiring. The first four are obvous. To make a workshop cost 25 stone, 30 wood, and 5 gold, make the line of code s25, w30 , g5; You can even make the workshop refund you, simply by making the costs negative. So if you wanted to make a bomb workshop cost 200 stone and 50 wood, but repay you 5 coins for building it, the code would look like this:
The upgrading and requiring costs are a little more complicated, but give you so many more options for custom shops and technology trees. Add uROOM_NAME in the cost list and the workshop will not be appear in the workshop build wheel. The room configuration file will save the information so you can upgrade to this shop from another (the one designated by ROOM_NAME). The requiring function uses rROOM_NAME. The workshop will be buildable from the selection wheel, although it will not be possible to build it unless ROOM_NAME is already built.
That covers all the fundamentals of room syntax. Now, let's practise with an example.
Let's say we wanted an OP workshop that looked like a doorway, healed us, and gave us the option to buy bombs and arrows. We want this shop to cost 200 gold, but give us 50 wood, 50 stone, and 20 coins back when we build it. We also want this shop to be upgraded from the quarters and be only buildable if we already have a siege workshop and an arrow shop. This is what we'd do:
Start with this:
ROOM_NAME; Entities/Rooms/Sprites/EDIT_THIS.png; HELP_TEXT; ROOM_ITEMS/FUNCTIONS, SEPARATED_BY_COMMAS; COSTS, SEPARATED_BYCOMMAS;
First we need a name for our shop, let's pick OP SHOP.
OP SHOP; Entities/Rooms/Sprites/EDIT_THIS.png; HELP_TEXT; ROOM_ITEMS/FUNCTIONS, SEPARATED_BY_COMMAS; COSTS, SEPARATED_BYCOMMAS;
Next, we need a path to the image file, so let's use the doorway image file, Entities/Rooms/Sprites/Doorway.png;
OP SHOP; Entities/Rooms/Sprites/Doorway.png; HELP_TEXT; ROOM_ITEMS/FUNCTIONS, SEPARATED_BY_COMMAS; COSTS, SEPARATED_BYCOMMAS;
Now we need to pick some help text, let's choose This shop is OP!
OP SHOP; Entities/Rooms/Sprites/Doorway.png; This shop is OP!; ROOM_ITEMS/FUNCTIONS, SEPARATED_BY_COMMAS; COSTS, SEPARATED_BYCOMMAS
Now we pick functions. The functions we want are heal, bomb, and arrow. You can see these three functions in the room_function section at the bottom of the room.cfg. We'll examine how to modify this section later. So we type bomb, arrow, heal; and put bomb first since let's pretend we want bombs to be the default buy option (what you buy when you press [E] next to a shop with multiple items). If we wanted to buy arrows by pressing [E] we'd just make the code arrow, bomb, heal; (You'll notice heal doesn't appear in the option wheel because it's a passive function; if you stand close to the doorway you will heal automatically)
OP SHOP; Entities/Rooms/Sprites/Doorway.png; This shop is OP!; bomb, arrow, heal; COSTS, SEPARATED_BYCOMMAS
Lastly, we need to determine the cost of the shop. We said 200 gold, and we get back 50 stone, 50 wood, and 20 coins. We also are upgrading from the quarters and require a siegeshop and an arrow shop. This is what we add: s-50, w-50, g200, c-20, uQUARTERS, rARROW WORKSHOP, rSIEGE WORKSHOP;
OP SHOP; Entities/Rooms/Sprites/Doorway.png; This shop is OP!; bomb, arrow, heal; s-50, w-50, g200, c-20, uQUARTERS, rARROW WORKSHOP, rSIEGE WORKSHOP;
And there you have it! An OP shop!
The last section deals with the items/functions that are available in the selection wheel of a built workshop. This section is directly linked to the previous section, so be sure that you fully understand how room syntax works before you continue to items/functions.
Room Items / Functions
Here is the section of code that lets you modify which items and functions a workshop has in its selection wheel:
#room_function syntax - function name; function actor name; function config file; function icon; function make sound; function icon frame; function icon frame size; function help text; costs , , , (g gold, s stone, w wood, c coins - none) ...
@$room_functions = bomb; -; -; Entities/Items/Sprites/MaterialStacks.png; Entities/Rooms/Sounds/BombMake.ogg; 12; 16; Bomb costs 20 coins; c20;
arrow; -; -; Entities/Items/Sprites/MaterialStacks.png; Entities/Rooms/Sounds/ArrowsMake.ogg; 10; 16; Arrow cost 1 coin; c*10;
catapult; -; -; Sprites/catapult.png; d; 0; 32; Construct a Catapult; w120, c20;
outpost; -; -; Sprites/outpost1.png; d; 0; 32; Construct an Outpost; w120, c50;
heal; -; -; -; Sounds/heart.ogg; 0; 0; Healing 2 coins per 1/2 heart; c2;
;
# - nothing
# - in room_functions as texture = don't add to menu - collide function
# d default build sound
# c*10 - buy as much as possible, max 10,
To edit your room items and functions, we'll be using this comment:
This is basically what you'll be editing to add/remove items, change their costs, or to change the sprites that display in the selection wheel. To make things simpler, you can use this as a template to create room functions:
Let's consider each block one by one.
FUNCTION_NAME; is the name of the item/function. It will not appear anywhere other than in your config files. This is the function/item name that is used in the workshop syntax that we worked on above. If you want an item to appear in your shop, it must appear exactly as it is named in your function section.
ACTOR_NAME; is the name of the actor that is used to make the item/function 'work'. Use the actor closest to one that you already have.
CONFIG_FILE_PATH; is the path to the configuration file of the item that you will be using. Usually, these files are found in Entities/Items/... You can put any file path here as long as it has the .cfg file extension.
ICON_FILE_PATH; is the path to the image that will display in the item selection wheel. Some are found here: Entities/Items/Sprites/... while others are in the Sprites/... folder.
MAKE_SOUND_PATH; is the sound that plays when you buy the item. Pick one that matches well with the sound the item might make irl. There are sound files here: Sounds/... here: Entities/Items/Sounds/... and here: Entities/Rooms/Sounds/...
ICON_FRAME; denotes the 'frame' within which you want to take your image to display. The easiest way to explain this is by example. If you open Entities/Items/Sprites/MaterialStacks.png, you will see a whole bunch of images, all placed in a single image file. The 'frame' refers to a section of the image that is occupied by one smaller image. The numbering system for franes starts at 0 and increases moving left to right, starting from the top of the image file. So as as example, in MaterialStacks.png, if you wanted to display two bombs, you would type in an icon frame of 13. If you wanted three logs of wood, you would type in 4, and if you wanted a single arrow, you would type 9. The icon frame works closely with the ICON_FRAME_SIZE, so make sure you understand how the numbering system works before you move on. (NOTE: You may run into issues when using files that have whitespace, such as Sprites/materials.png. For these files, just pretend that there are images equal in size to the others in the whitespace to calculate the icon frame number.)
ICON_FRAME_SIZE; is the size, in pixels, of the icon frame for the sprite displayed in the item selection wheel. Icon sizes are always the same width and height, so you only need to enter one number here. To calculate the icon frame size, find out how wide the image size is in pixels and divide that number by the number of sprites on a row. For MaterialStacks.png, the width is 48 pixels and there are 3 sprites per row. 48 / 3 = 16, therefore the icon frame size is 16.
HELP_TEXT; is the text that displays in the center of the options wheel for items in a shop.
COSTS, SEPARATED_BY_COMMAS; are the costs for the items / functions. You can make some things free, such as healing or traveling, or you can make them cost resources. Use the same syntax as was explained above.
