Add-On Room Tutorial

By: johnnyutah

Introduction
Hello, this tutorial will be covering the basics of how to create an add-on room.
The actual instructions will be step-by-step along with images to make them easy
to understand. Everyone has different levels of understanding when it comes to
the game and Blender. As a result, this tutorial is not meant to be extremely
technical. You do not need to have any scripting knowledge at all to understand
this tutorial. However the tutorial does assume the reader has setup the blender
tk17 script and is “ready to go” as far as the tools are concerned.
The tutorial will give a brief overview of the folder structure, the important (.bsb) files to edit, some basic
blender functions, followed by step-by-step instructions for everything.
I really recommend you read the tutorial in order (or at least skim through the sections you think you know
100% about) because later on I will be referencing materials covered in previous sections.
In the end I’ve included a Frequently Asked Questions (F.A.Q.) section of some potential issues the reader
might encounter and potential solutions.

Few words from the author:

The Add On Room process can be a long process, if you’re tired, I strongly recommend you
take a break and continue later. Otherwise you could end up making silly mistakes, and
then become frustrated. Take little steps and try to understand what is happening in the
current section before moving on.
I’ve made more mistakes in modding than I can count in this life-time, chances are any
mistake you make I’ve done it before XD. It may sound cliché but try to see those mistakes
as learning opportunities. So try not to be too discouraged, if there is a particular point you don’t understand
feel free to comment in my thread or send me a private message. I am always glad to help out if you’re willing
to learn ^_^
Tips and Hints
#1: Save save save! This includes your blend and .bs files
#2: When working on a room with many objects, it is a good idea to set small goals and stop at every 10, 15 or
20 objects and test the room.
#3: Try to keep an open mind, don’t let this rile you up; it’s just a program and game. Treat it as a hobby and
things become more enjoyable.
Table of Contents
Introduction ............................................................................................................................................................ 1
Getting Started........................................................................................................................................................ 3
Folder Structure Overview ...................................................................................................................................... 4
Images Folder ...................................................................................................................................................... 5
Scenes Folder ...................................................................................................................................................... 6
Scripts Folder ....................................................................................................................................................... 7
Step-by-step instructions ........................................................................................................................................ 8
Step 1: Import the Body for reference ................................................................................................................ 8
Step 2: Import the room ..................................................................................................................................... 9
Step 3: Organize the objects ............................................................................................................................. 10
Step 4: Converting / Saving Textures ................................................................................................................ 10
Step 6: Editing the 3D Mesh .............................................................................................................................. 13
Step 7: Converting the 3D Mesh ....................................................................................................................... 13
Step 8: Texture Normal Altering ....................................................................................................................... 21
Step 9: Cleaning up the room###.bs file ........................................................................................................... 22
Step 10: Creating and managing positions ....................................................................................................... 23
Step 11: Scripts .................................................................................................................................................. 26
Step 12: Testing and final touches .................................................................................................................... 29
Frequently Asked Questions (FAQ) ....................................................................................................................... 30
1) My room doesn’t show up in the room selection? ................................................................................... 30
2) My room appears in the room selection, but when I load it there is nothing its just black? ................... 30
3) My room shows up fine, but there is only one position? .......................................................................... 30
4) My room is gray, there are no textures? ................................................................................................... 30
5) My game crashed, what happened? ......................................................................................................... 30
6) Help, X isn’t working correctly what can I do? .......................................................................................... 30
Getting Started
First make sure you have the necessary software and tools, mainly the following:
Software Requirements:

 Blender 2.64
 TK17 blender script
 (.bsb) decode/encode tool
 (.txx) decode/encode tool

A sample room has been provided along with this tutorial and the specific instructions will be based on it.
However the general idea can be applied to any other room.

Note 1: This tutorial will reference text and files that has “###”, this is only a placeholder, you need replace it
with a room ID number that is not taken in order for the room to work. (example: Room###  Room201).
You can easily do this by re-naming the folder, or file itself.

For the text inside the .bs files, press CTRL+H to find + replace, enter ### and replace it with a room ID.

Note 2: If you already have your own room in mind, you are welcome to use that instead, just make sure you
can get it into a format that Blender can import. Google your file extension + blender import if it isn’t in the
blender default import options.
Folder Structure Overview
In the tutorial package, you should have a folder called “Custom.03.R9ZRoom###” and inside should be three
folders titled: Images, Scenes, and Scripts.
Images – Contains your textures
Scenes – Contains your 3D Mesh data as well as position data
Scripts – Contains various information such as the room ID, description, as well as position reference
Please read the below sections for a more detailed explanation of the files that go in these folders.
Images Folder
This folder contains all the texture for the room including the icons.
\Images\Q=Tex032M\Luder\GUI\ R9ZRoom###_Icon.png  is the texture of the icon of the room
\Images\Q=Tex032M\Luder\Room\R9ZRoom###\ R9ZRoom###_Object001.png  are the textures for the
various meshes of the room.
The image sizes in pixels must be the following:
128x128
256x256
512x512
1024x1024
2048x2048
4096x4096
Or any combination (ex: 512x1024). The icon is 128x128, you could make it bigger but that is not necessary
since it is just an icon. Make sure the images are in the .png format.
Scenes Folder
This folder contains your actual 3D Mesh file.
\Custom.03.R9ZRoom###\Scenes\Luder\Room\R9ZRoom###\ R9ZRoom###.bs
Right click it and open it with wordpad. You should get something similar to the figure 1 below:

Figure 1

Scroll down and you should see “blocks” for different objects, they are the shader, texture, vertex, normal,
and uv data of the various objects. Note that anything with a “//” in front is not read by the game. If you scroll
near the end you should see position data as well. I will explain more in detail what you need to do with this
file later on in the step-by-step instructions.
Scripts Folder
There are quite a few things in this folder I’ll just briefly explain the important ones.
In Luder\Common
\Scripts\Luder\Common\ R9ZRoom###.bs  contains room ID, Icon and other settings.
The only thing you really need to change is the ### to the room ID of your choice.

\Scripts\Luder\Common\ R9ZRoom###_Description.bs  contains name and description of room

Self-explanatory, give your room a name and description if you want.

In Luder\Room###
\Scripts\Luder\Room###\ . . . . .
There are a lot of files in here, however only three needs to be edited:
AcRoom.bs  Position and lighting related
AvFurnitures.bs  Position (sex-type) related
AvFurnitures.L=EN.bs  Position name and description
Step-by-step instructions
Step 1: Import the Body for reference
Open Blender 2.64, first, using the Tk17 addon script import body01 or body02 into blender. Once you do,
press “A” to select all. Now “Shift + Left Click” the body_subdiv_cage (this unselected the body) with
everything except the body selected, press “X” and delete.
What should have happened is you should now only have a female or male body in your blender 3D view
(figure 2). The reason you want to do this is so once we import the room we can use the body as a reference
to how big the scale of the room needs to be.

Figure 2

Before we move on, I want to bring your attention to the Object Mode and Viewport Shading options near
the bottom of blender. Object Mode can be toggled to Edit Mode via “TAB” button on your keyboard. You can
only make edits in Edit Mode and import / export in Object Mode. Viewport Shading give the objects in your
viewport different shading. Try clicking them and see what each of them does.
Wireframe for example is very useful as it lets you basically see through everything. You can press “Z” to
toggle between solid and wireframe shading.

Figure 3
Step 2: Import the room
Next, go to File>Import>wavefront(.obj) and navigate to the simple bedroom folder and import the
simplebedroom.obj into blender.

Figure 4: Import the room

You should get something similar to figure 5 below.

Figure 5: The room imported

Step 3: Organize the objects
If you remember in figure 5, once you imported the room there were a lot of new object names that showed
up in the upper right side. Right click each one and starting from the top rename them as “z01”, “z02”, …. Etc.
In the end you should have something like figure 6 below.
You can organize them in a special way if you want to, for example z01-z04 is the walls, the z05-07 is the inside
or you can just go down the list. It really is just a personal preference in the end it doesn’t really matter. What
is important here is you make a habit of organizing the objects in some kind of numbering system because it
will save you lots of headache down the road when you need to troubleshoot any issues.
TIP: For large amount of objects, once you are done naming an object, click the “eye” symbol to hide the
object Or press “H” as the shortcut. You can always press “ALT+H” to show everything once your done.

Figure 6: organize your objects

Now save your file. Save it as something that makes sense to you and in a place you can easily search for later.
I like to give it a name that easily identifies what the file is (ex: simple bedroom) and then save it in the same
location as all the textures and other stuff (ex: simple bedroom folder)

Step 4: Converting / Saving Textures

Click z01 and go to uv editing in the layout pane like figure 7:

Figure 7: Checking the uv layout and saving textures

You should get something similar to Figure 8 below. On the right side is your 3D viewport view, and on your
left side is the uv layout / editing view. If the image is not showing, you can press “ALT+R” to reload the image
or click image>reload image.
Make sure that in your viewport, with z01 selected, that you are in EDIT MODE. Do not worry if the uv layout
is not directly on the texture, it does not have to be. As long as the actual image in the 3D viewport on the
right looks correct you are good to go.
If you feel inclined you can click in the uv edit side and press “A” to move around the uv layout, you should see
the image to the right change along with it. Press CTRL+Z to undo.

Figure 8
When you are comfortable, click image>save as and save it in the
\Custom.03.R9ZRoom###\Images\Q=Tex032M\Luder\Room\R9ZRoom###
Save it as R9ZRoom###_Object001.png Make sure you choose the .png option. Blender has a built in texture
converter so that is nice. (See figure 9)
NOTE: Replace ### with a correct ID. Example: R9ZRoom123_Object001.png

Figure 9: Saving and converting the textures

Now repeat what we just did with the other objects. In your images folder you should have:
R9ZRoom###_Object001.png
R9ZRoom###_Object002.png
R9ZRoom###_Object003.png
….etc

Once you are done with everything save your file.

Step 6: Editing the 3D Mesh
This step is not always necessary, this room’s scale is relatively to scale to the body. On the other hand if your
room needs to be scaled up or down, simple press “A” to select all the objects, deselect the body (shift + left
click the body) and press “S” and move your mouse to scale up or down everything.

Figure 10: common transform options

You can also move the cursor to translate (move in the x, y, or z direction) certain objects if you need to.
Figure 10 are the common ones you use.
Remember, in the Viewport Shading, wireframe helps you see the objects visually. Once you are satisfied with
the scale and location, save your file. Then save your file again. as a new file name except with a 2 or _test at
the end. (example: simple bedroom.blend and simple bedroom2.blend).

Step 7: Converting the 3D Mesh

Okay, there are many different ways to go about this, the way I am about to describe may not be the fastest
way, but I can guarantee it will work with minimal issues. This is the step that once the user is comfortable
with can experiment different ways of doing things so it’s the most efficient for him or her. Make sure your
using simple bedroom2.blend file.
First, open up \Custom.03.R9ZRoom###\Scenes\Luder\Room\R9ZRoom###\ R9ZRoom###.bs , resize it so its
on the right side of your screen. (this will make more sense soon)
Now in blender, do the following steps carefully:
1. Import Tool09 (or 08, whatever it doesn’t have to be 09)

Figure 11: Import the tool

2. Click object z01 and go into edit mode (TAB)

Figure 12: Select your object

3. While in edit mode, press “A” so you are DESELECTING the mesh

Figure 13: deselect the mesh in edit mode

4. Go back to object mode

5. SHIFT+LEFT CLICK z01
6. SHIFT+LEFT CLICK tool09
 Figure 14: Select your mesh, then select the tool

7. Press CTRL+J to join the two meshes

Figure 15: join the two meshes

8. Go into edit mode (TAB) and only tool09 should be highlighted

 Figure 16: go into edit mode

9. Press X to delete tool09’s mesh

Figure 17: delete the tool’s mesh so only the room mesh remain

10. With tool_mesh selected, (in object mode) generate with the following options in the export menu:
 Figure 18: Export

Okay, you should now have a new window open with a tool09.mod00.bs file available. Click it and open it with
a wordpad.

Figure 19

You should see a bunch of stuff, scroll down till you see SPolygonGeometry

First, you can ignore everything else that is not inside the greenbox. I don’t really want to get too technical
here but the green block contains your vertex, normal, and UV data. Please note the small red boxes.
 Figure 20

You should still have your room###.bs file open, position the tool09.bs file and the room###.bs file so they are
side by side like figure 21:
 Figure 21

You want to change the red, blue, yellow boxes with the values of the Room###.bs file. This means changing:

Local_15 -> local_9

Local_21 ->local_15
Stool_meshShape -> Ssky_meshShape
Local_21 -> local_15

Once you have done the following, highlight the green box starting from “SPolygonGeometry” to “};” in
tool09.bs copy and paste it in the room###.bs side. Your final result should look like figure 22 below:

Figure 22

What you have just done is you have copy and pasted z01’s mesh, normal, and uv data into the room file.
After you have done this step, you can close the left wordpad (tool09bs) file. Go back into blender, delete
tool_mesh.
Step 8: Texture Normal Altering
A mesh’s normal is the direction in-game that you will visibly see the texture. You usually do not need to worry
about this, however in certain circumstances, it is better to have the textures only on one side of the mesh
(example walls) so you can see through the wall from the outside, but still see the wall texture from the inside.
So how can you tell which side the textures are facing? In Blender click z02, go into edit mode and under mesh
display click the face normal button as shown in figure 23 below:

Figure 23: Display Normals

The direction that the lines are sticking into are the direction you can see the texture. In this case, in-game
z02’s texture can only be seen when viewed from the inside, and invisible when viewed from the outside.
This can be adjusted in the room###.bs file, if you look under object 002, you should see the lines
RenderShader.MultiDrawLayer I32(37);
RenderShader.CullEnable False;

These two lines causes the game to draw the texture of the object in-game on both sides regardless of the
way the normal is facing. If you do not want this feature, simply highlight these two lines and delete them. On
the other hand, if you want this feature, you just need to copy and paste them in the “RenderShader” block as
shown in Figure 23 below.
 Figure 24: Texture Normal and MultiDraw

Generally, walls do not need this feature as they obstruct the player’s view if you can see it from both sides of
the mesh. However in the end you will need to make your own choice whether or not you want this feature or
not for every single object.
Now that we have a basic understanding of texture normal, you need to repeat Step 7: Converting the 3D
mesh for the other objects. Remember to change your local_##, and Object.Name so it corresponds to the
correct object.

Step 9: Cleaning up the room###.bs file

Once you are done converting all 7 objects, you should see that the room###.bs file actually has objects all the
way up to like 60. Since you don’t really need those extra data blocks, you can go to the end of object 060,
(click near the end of the block) go to the end of object 007, and shift+left click. This should highlight
everything from Object 008 to Object060. Delete the unused objects and save the file.
Step 10: Creating and managing positions
***This step has ties into the script files***
Scroll towards the end of the room###.bs file, you should see something like Figure 25:

Figure 25: Positions

I will try to describe what the data in the colored boxes mean below without getting too technical and
confusing.
Blue = Name of the position defined in the room file. In this case, it is called “floor01” this will be referenced in
the script files.
Green = The X,Y,Z translation and rotation of the location. Think of this particular data block as the “master” or
“parent” location. This means that Position02, Position03, and Position04 will all based on this block.
Red = The X,Y,Z, translation and rotation of the location based on Sfloor01_position_group.
What does this mean? It means anything you put in sfloor01_position_group will be added to the position02
values.
Example:
STransform :local_9293 . {
SSimpleTransform.Translation Vector3f( 1, 0, 0 );
SSimpleTransform.Rotation Vector3f( 0, 0, 0 );
Object.Name "Sfloor01_position_group";
};
TTransform :local_9294 . {
TNode.SNode STransform :local_9295;
TNode.Parent TTransform :local_9292;
Object.Name "position02";
};
STransform :local_9295 . {
SSimpleTransform.Translation Vector3f( 1, 0, 2 );
SSimpleTransform.Rotation Vector3f( 0, 0, 0 );
Object.Name "Sposition02";
};

This means the position02 in game will be:

X=1+1=2
Y=0+0=0
Z=0+2=2

Figure 26 below shows the coordinate system. Note that this is if you imported the body01 and did not change the
body’s location or rotation.

Figure 26: Coordinate system

TIP1: When you import your room, try to make sure one of the floors or position is level with the body, this
will help you when choosing a default position to reference from. (example center of the room or the 1st floor
of a building)
TIP2: You can use Blender units as a reference, however it is not exact. (meaning X = 1 in blender does not
mean X = 1 in TK17) You will probably spend some time going back and forth testing the location in game
and coming back to make changes.
Depending on the room and how many location you want to create, you will need to make the appropriate
changes in the scene file and the script file. If you scroll down, you will see that floor01, floor02, floor03 are
defined. They also have position02, position03, position04 defined as well. This gives you a possible 9 pre-set
positions in-game.
If you want to add more, just follow the same procedure and change the local_## to match the numbering
system.
Anyways, go to position02, under sfloor01_position_group and change it to the following:
STransform :local_9295 . {
SSimpleTransform.Translation Vector3f( 0, 0, 1 );
SSimpleTransform.Rotation Vector3f( 0, 90, 0 );
Object.Name "Sposition02";
};

This position should move the character forward and rotate it 90° around the y axis. I recommend leaving the other
positions alone for now (they are all 0,0,0 by default). We can always come back here later. Anyways before you do
anything else save the .bs file.
Step 11: Scripts
Okay, we are almost done. Go to the script folder and open the following files with wordpad:
In Luder\Common
1) \Scripts\Luder\Common\ R9ZRoom###.bs  contains room ID, Icon and other settings.
The only thing you really need to change is the ### to the room ID of your choice. Save afterwards.

2) \Scripts\Luder\Common\ R9ZRoom###_Description.bs  contains name and description of room

Self-explanatory, give your room a name and description if you want. Save afterwards
---------------------------------------------------------------------------------------------------------------------------------------------
In Luder\Room###
\Scripts\Luder\Room###\ . . . . .
There are a lot of files in here, however only three needs to be edited:
AcRoom.bs  Position and lighting related

Figure 27: AcRoom.bs file

You can change the lights01 if you want (example: 05 is the bathroom light) but you can just leave this
untouched for the most part.
Hey look, its floor01_position_group. Remember seeing this in the scene room###.bs file? This is one of the
files in the script folder that references to it. Also note “.ImportNamespace” this is referencing another file in
this folder. Make sure what you have in your scene file matches the name here. (You can add more or delete
them as needed)
Anyways the only thing in this file that you should need to change is the ### into a valid ID. Save the file after
you are done.
---------------------------------------------------------------------------------------------------------------------------------------------
AvFurnitures.L=EN.bs  Position name and description

Floor01 should be the same name as the one you have in .ImportNamespace in the previous file, it is also
referenced in another file. “Floor 01” is the actual name that appears in game. You can name this anything
you want. (example: bathroom, kitchen, ceiling…etc)
The only thing you should change here is the text inside the quotation marks: “________” when you are
satisfied, save the file.
---------------------------------------------------------------------------------------------------------------------------------------------
AvFurnitures.bs  Position (sex-type) related
Floor01 is referenced here, like it was in the scene file and the two previous .bs files in the script folder.
Floor01_position02 refers to what you think it means: position02 of the floor01_position_group.
Now regarding TYPE, according to the in-game room files the following are the available types:
FLOOR, TABLE, CHAIR, WALL, SOFA

NOTE: I am not an expert in this area, as all the poses can be used in pose edit mode, these commands only
dictates what is available in the other “Play” Modes. I am not 100% sure what controls how a pose is
considered “FLOOR” or “TABLE” but I think it depends on the location it was made in pose editor.

Figure 28

For a given location or position, you need to define the “TYPE” of poses you can use at that location.
Unfortunately, I have not found a way to simply enable all poses for a location without having the location
duplicate. As a result you must define specific TYPES for a given position.

I’ve given examples on how to enable multiple positions here, I think its pretty self-explanatory, all you need
to do is to copy and paste and change the “Floor##” and add in “position##” if you wish to add pose options to
a locations. In the example above, TYPE: FLOOR poses are available for Floor01 and Floor02 position02. While
TYPE: FlOOR, SOFA and TABLE are available for Floor03 position02, 03 and 04. This means floor03 will have
three duplicates. Anyways you do not have to really change anything here unless you want to experiment.
When you are done, save the file.
Step 12: Testing and final touches
So if you followed my instructions and made the necessary changes and saved the file. It is time to go back and
encode all the [.bs] files into [.bsb] files using the bsb tool. Once all the .bs file has been encoded, take the .txx
tool and encode the Custom.03.R9ZRoom### folder into Custom.03.R9ZRoom###.txx
Next, assuming you have everything done, the only thing left is to enable texture support of your room in the
AddOnScript File. So take the latest Custom.02.R9AddOnScripts.v###.txx file and decode it. Go to
\Custom.02.R9AddOnScripts.v4.09\Scripts\Luder\Common\
And open the Mod_R9ZRoomAddon.bs file with a wordpad.
Scroll to the end, add in your room (you can just copy one of the previous rooms and use the “find and
replace” command) Example figure 29 below:

Figure 29

When you are done, save the file, encode it with the bsb tool. Then (Make sure you have a backup
addonscript file) encode the addonscript folder back into a .txx file.
Put the New addonscript file and the Custom.03.R9ZRoom###.txx file into your archives (don’t forget to delete
the older script) Now launch your game and cross your fingers.
A thing to remember here is when you are finally in the room in-game, don’t forget to take a screenshot and
re-size it for the icon (\Images\Q=Tex032M\Luder\GUI\ R9ZRoom###_Icon.png)
Hopefully mostly everything is successful and you at least see a room appear in the room selection. Even
better is if you load the room and it appears.
If everything worked out congratulations! If not, please read below in the FAQ section to diagnose your
problem.
Frequently Asked Questions (FAQ)
1) My room doesn’t show up in the room selection?
Check the addonscript folder, make sure everything is correct, check the semi-colons, brackets and spacing.

2) My room appears in the room selection, but when I load it

there is nothing its just black?
Check your Custom.03.R9ZRoom### folder, make sure all the ### has been changed to a VALID ID. It needs to
all MATCH, this means the folders, and the ### inside the .bsb files.

3) My room shows up fine, but there is only one position?

Make sure you properly defined the positions in the scene file, and referenced them in the script files. For
sanity, I would recommend naming everything the same for a particular location. (example: Floor01 = Floor01
in all the other places)
What happens is you can define 9000 location in the scene file but if the AcRoom.bs, AvFurnitures.bs, and
AvFurnitures.L=EN.bs isn’t properly referenced, then the game will not recognize those locations.
If you made extension edits to those files, it’s important that you did not forget a bracket or semi colon.
Missing a single “}” or “]” is lethal.

4) My room is gray, there are no textures?

Make sure you named the textures the correct name. That they are defined in the addonscripts file properly.
Also make sure in the scene file that each object references to the correct texture. (they should be by default
if you changed all the ### into the same ID)

5) My game crashed, what happened?

Either your room has too many high-resolution textures (the game can’t handle the memory usage). Or you
really messed up the scripting somewhere. First try lowering the resolution of all your textures or temporarily
replace them all with 128x128 white squares.
If the game loads, it’s a memory issue. If not, check your scripts.

6) Help, X isn’t working correctly what can I do?

For random things, one recommendation I have is download a working addonroom. (example the simple
bedroom room 201). Having something that is proven to work as comparison could help you find out what you
did wrong.