From Alcugs

Note: Anything extracted from any Plasma Resource Files is property of Cyan Worlds, Inc. You may not use these assets without recieving written permission from Cyan Worlds, Inc.

Please read this Notice from Cyan about Age Creation before continuing.

Previous: Conditional Objects Contents Next: Compiling Python Scripts

Contents 1 Introduction 2 Tools 3 1 - Creating the Journal in the Age 3.1 Adding Images in your journal 4 2 - Creating the Python files 4.1 Change some needed Code 4.2 Add the Journal code 5 3 - Formatting the Journal content using PBML

Introduction

Foreword: This an ‘intermediate’ level tutorial, so I’ll assume you have basic knowledge of Blender & the Age building process.

Adding journals in Ages has already been covered in parts through various tutorials, but parts of these are now outdated and new features have been added since. So we will go through the whole process here to create a clickable Journal complete with text and pictures. We will especially focus on the more technical aspects (Python coding). This tutorial might seem long on first reading, but once you have successfully created your first journal, the process is easy and quick to repeat.

(Note: we will be talking about ‘Journals’ as opposed to ‘Books’, which are Linking Books in Uru, and are created differently.)

Tools

First of all make sure we have all the right tools . Beside a working installation of Blender and the Prp plugin you will need to install and configure PlasmaShop.

1 - Creating the Journal in the Age

As this is not the focus of this tutorial we will create a very simple book.

In the top view add a Cube; go in Edit mode, select all and scale it down along its X axis and then along its Z axis. so that we have a rectangle that somehow look like a very simple book. It should be around 0.5 unit wide x 1 unit long x 0.5 unit high (Remember that 1 Blender unit = 1 Foot / 30cm and an Uru avatar = 6 feet high). Name it ‘JournalObject’.

You will need a texture for the cover. I have quickly done [This one] which we will use here. (It is free of rights, feel free to use it if you want). Map it as you need on the mesh.

Note: Two different pictures are used for the book cover: the one used for the book that is displayed in the Age and the one that is displayed on screen when you click the book (what is called the ‘GUI’ Journal). Ideally the cover picture used for the ‘Age’ book should be a lower resolution version of the texture used for the GUI journal. For simplicity we will use the same texture for both here.

To make the journal object clickable you will need to add a property pointing to the Python file we will make later on. Select the book and display the ‘Logic’ panel. Add a ‘String’ Property and give it the name ‘clickfile’ and give it as a value the name of your Age. This value will be the name of the python file we will create later.

We will also need to add a ‘clickable region’. This region tells Uru where an avatar can click the book. To do this, use Scripts->Add->PyPRP->"Add a Clickable Region" (in the Scripts window). You now have a new click region in layer 2. (If you want to move it to another layer, hit the M key; when the layer boxes appear, click on the layer you want.) Then resize it (in Edit mode) to be large enough to encompass the book and an avatar. It should be around 4x4x7 units.

Note: if you resized the region in Object mode, you'll need to apply the scale to the region's vertices; otherwise, the exported click region will not be the right size in Uru. To do this, press Control-A, then click on "Apply Scale And Rotation" in the popup menu that appears.

Also if you want to put your journal on something (a desk or a table) it should be around 3 units above the ground to be at 'hand' level (see avatar on the screenshot for instance).

Finally, you will need to select your Age Book and set the ‘AgeSDLHook’ property to ‘True’. This will enable Python scripts for the Age. If you forget this your journal won’t work..

Note: If your age book does not have an AgeSDLHook property, then add a Bool property, change its name to AgeSDLHook (the case must be correct), and click on True.

Adding Images in your journal

If you plan to add pictures in your journal you will need to have them somewhere in the Age outside of the journal so that the textures are saved in the textures.prp file during the Age export process. For each texture used in the journal (cover or images) just add a simple plane with the corresponding texture in the Age somewhere hidden from view. (Just put it somewhere underground or inside a wall.)

You can now safely export the Age and quit Blender; we won’t use it anymore for now.

2 - Creating the Python files

Several other tutorials go over how to properly create Python files so we won’t go to much in the details of the process here but focus on the journal aspect.

Warning: I’m not a Python expert so this is only a straight step-by-step process. If you follow it closely it will work fine though.

Journals in Uru are kept inside a Python file, which is in turn part of the Age PAK Python file. Both being kept in the Python folder of Uru. They can be on a stand-alone file or integrated as part of a larger Python file. For the sake of simplicity we will use the second method here and use an existing Python file.

Start Plasmashop and create a new Python PAK ( File > New > Python PAK ); Plasmashop will ask you to save it; give it the name of your Age. In the left window your python Pak should appear under the ‘Python’ folder. Warning: As long as your Pak is ‘empty’ it will not be actually saved; you will need to first add a Python file inside. Select File > New > Python File. Your new Python file should appear and your screen should look something like the screenshot above.

Save you new python file right now; give it the name of your Age. You can save it where you want, but it’s easier to just keep it in the Uru Python folder. (If your PAK and Py file do not appear in the left panel you might need to refresh the window, press F5).

Change some needed Code

We will now add the python code in the file for the journal. First you will need to change the class name ‘myResponder’ to your Age name.

Python
class MyAgeName(ptResponder,):

Also you must create an ID for your script. This is a unique number that identify your script for Uru (much like the Age sequence prefix). There is no ‘official’ Cyan rule for that, so we use the form: ‘AAASSS ‘ Where ‘AAA’ is the Age Sequence prefix, and ‘SSSS’ is any ID number that's unique among the Age's scripts. (Since an Age can have several python scripts). So if your Age sequence is 183 and this is your first script for the Age the ID should be 1830001. So you need to change

Python
self.id = <insert ID here>

and replace <insert ID here> with your script ID like this:

Python
self.id = 1830001

Add the Journal code

Let’s add the code for the journal itself. First at the top of the code add this:

Python
from UruAgeManager import *
from xPsnlVaultSDL import *
actClickableObject = ptAttribActivator(1, 'Act: Clickable Object')
ObjectMsg = ptAttribString(2, 'Object String')

Under the ‘def OnNotify’ line remove ‘pass’ and put this:

Python
uam.handleNotify(state, id, events)
if (id == actClickableObject.id):
    if (ObjectMsg.value == 'JournalObject'):
        uam.showBook('Insert book code here', self.key)

This is the code that will check when you click the Journal object in Uru and will display the Journal on the screen. The "ObjectMsg.value == 'JournalObject' " part, checks which object is clicked, so the 'JournalObject' value must be the exact name of the object in Blender. (in this case we had named it ‘JournalObject’ so this is good.) The ‘Insert book code here’ part is where we will insert the actual Journal text and code (Make sure to keep the quotation marks or the code won’t work!). Your whole code should now look something like the screenshot bellow.

Note: This code will show journals with normal-looking pages, if you want to have a journal with blue lined paper (like the DRC notebooks) just change uam.showBook to uam.showNotebook.

You can now save the python file. Finally let’s add it to the PAK: go back to the PAK window, click ‘Add Files’ and select your python file. If all goes right you should be greeted with a “Done!” message. Each time you modify and save the python file you need to it again to the PAK.

Note: If you tried adding the python file and you get a "Range Check Error", that means that the PAK file is corrupt. Here's a workaround:

• Exit PlasmaShop
• Go to the Python directory of your Uru installation
• Delete your age's PAK file
• Make a copy of UruAgeManager.pak and rename it to your *ge
• Restart PlasmaShop
• Double-click your age's PAK file
• click Add Files..., then select your age's PY file
• Select the other files in the PAK file and click the Delete Files button

Important: Python is very sensitive about the formating of the code. Make sure when you copy the code above to use ‘tabulations’ instead of spaces to shift the beginning of each line according to the code above; if something is wrong there, Plasmashop will return a ‘Syntax error’ when adding the python file to the PAK. If you get such an error make sure you have precisely copied the code above and check your tabulations.

If all went right so far you can now test your journal in the Age. (If you hadn’t exported the Age before do it now.) If you click the Journal you should see your journal (without a cover for now) and inside there should be a single page saying “Insert book code here”. Congratulations you have successfully created your first functional journal! The process might have been long, but now that you have the needed files, if you want to add a new journal in you only need to duplicate your python code and change only what is needed.

Now let’s look at how we can finally put in the Journal content and make this journal more interesting.

3 - Formatting the Journal content using PBML

All journals in Uru (except for the personal journal in PotS) are formatted with a script language called PBML (Plasma Book Markup Language), which is based on HTML; so those who are familiar with it should have no difficulties; and for those who aren’t it’s very simple. This language has a limited set of instructions to lay out the text, change fonts, display the journal cover, and add pictures; everything to make a nice looking journal.

Because this is a large topic, there is a dedicated PBML page here PBML Journal Code.

Inserting the PBML code for your journal in the Python file is the last step. Once you have done this you have everything you need to know to make journals.

Previous: Conditional Objects Contents Next: Compiling Python Scripts