Tutorial: simple journals and Linking Books

Help bring our custom Ages to life! Share tips and tricks, as well as code samples with other developers.

Tutorial: simple journals and Linking Books

Postby Sirius » Sat Aug 03, 2013 3:07 am

Hello everyone,

Here is my tutorial to create basic journals and linking books without having to mess up with Python.
(If you need more features and know how to use Python, check D'Lanor's dynamic book template)
It requires the Offline-KI.
If you have any question, or encounter issues, feel free to post them in this topic.

UPDATE: Karkadann got it working with 3DsMax too, so check the Max part of this tutorial !



Blender - Creating a journal:

You'll need to create a book model (obviously) and put a logic region around it. When the player is in this region, the book will become clickable.

Settings for both your book and the clickregion:
logic panel:
- check "Bounds"
- change the bounds type to "Convex Hull".
- check the "Actor" button


Then, you'll need the following AlcScript:


Code: Select all
<book object name>:
    physical:
        pinned: true
    logic:
        modifiers:
            - tag: click
              cursor: poised
              flags:
                - localelement
              activators:
                - type: objectinvolume
                  remote: <region name>
                  triggers:
                    - any
              conditions:
                - type: activator
                  activators:
                      - type: picking
                - type: objectinbox
                  satisfied: true
              actions:
                - type: pythonfile
                  ref: $click
        actions:
            - type: pythonfile
              tag: click
              pythonfile:
                file: xSimpleJournal
                parameters:
                    # activator: clickable object
                    - type: activator
                      ref: logicmod:<book object name>_click
                   
                    # journal name (ageresources/<YourAge>--<journal name>.txt, or <YourAge>_<journal name>.py)
                    - type: string
                      value: <journal name>
                   
                    # notebook (true) or normal book (false)
                    - type: bool
                      value: true
                   
                    # book X scale
                    - type: float
                      value: 1.0
                   
                    # book Y scale
                    - type: float
                      value: 1.0



It's a bit long, but there are only a few things that interest us.
First, change <book object name> and <region name> to whatever you named your book object and region object (minus the <> symbols).
Now, let's look at the parameters:

Code: Select all
# activator: clickable object
- type: activator
  ref: logicmod:<book object name>_click


This is what makes the book pop up when you click it. Since you already changed <book object name>, there is nothing else to do.


Code: Select all
# journal name (ageresources/<YourAge>--<journal name>.txt, or <YourAge>_<journal name>.py)
- type: string
  value: <journal name>


<journal name> is the name of your journal (NOT your book object in Blender). Try to put only letters and numbers in it, but no special character (for instance: RicksJournal3).


Code: Select all
# notebook (true) or normal book (false)
- type: bool
  value: true


This changes the appearance of the book pages. Leave it to true if you want it to look like a notebook, change it to false if you want it to look more like an old journal/linking book.


Code: Select all
# book X scale
- type: float
  value: 1.0

# book Y scale
- type: float
  value: 1.0


These two control the size of the book. Usually, a book has a scaling of (1.0, 1.0). But some books like the Relto book are a bit smaller (0.75, 1.0).
Note: only values between 0.0 and 1.0 will work.


Now, on to writing your journal...
In Uru's folder, you'll see a directory called "ageresources". Create a new text file in it, name it <YourAge>--<journal name>.txt (minus the <> symbols)
Then, simply write your journal in it :)

If you want additional things, like a cover for your journal, or put some images in it, change the font, check the part about Plasma HTML.



Translation:
If you want to add a french or german translation of your book, write it in <YourAge>--<journal name>_french.txt or <YourAge>--<journal name>_german.txt



[Advanced users]
Some people prefer to write the journal's content in a Python file instead of a text file, to make sure players won't have access to the ageresources folder.
If you want to do so:
- make sure you have a basic understanding of the Python syntax
- write your journal content in <YourAge>_<journal name>.py, in a variable named xJournalContents.
- put "py_" before the book name, this should give you: "value: py_<journal name>"
You can add a translation in <YourAge>_<journal name>_french.py or <YourAge>_<journal name>_german.py.





Blender - Creating Bahro Linking Stones:

Bahro stones work like Linking Books, except they have less complicated options. So it's a bit easier to get started with these.

The Blender settings for the bahro stone and the clickregion are the same as for journals, so refer to that part of the tutorial if you don't know how to set them up.
Additionally, you'll probably need a texture for your Linking Panel. See http://alcugs.almlys.org/Offline-KI/TechnicalDocumentation to know what dimensions to use (note: currently it is impossible to access this website).

Now, the AlcScript for a Linking Stone:


Code: Select all
<stone object name>:
    physical:
        pinned: true
    logic:
        modifiers:
            - tag: click
              cursor: poised
              flags:
                - localelement
              activators:
                - type: objectinvolume
                  remote: <region name>
                  triggers:
                    - any
              conditions:
                - type: activator
                  activators:
                      - type: picking
                - type: objectinbox
                  satisfied: true
              actions:
                - type: pythonfile
                  ref: $click
        actions:
            - type: pythonfile
              tag: click
              pythonfile:
                file: xSimpleBahroStone
                parameters:
                    # activator: clickable object
                    - type: activator
                      ref: logicmod:<stone object name>_click
                   
                    # destination Age filename
                    - type: string
                      value: <age name>
                   
                    # name of spawn point to link to (skip to link to default link in point)
                    - type: string
                      value: <sp name>
                   
                    # name of linking panel texture
                    - type: string
                      value: <texture name>


Replace <region name> and <stone object name>.
Now, you'll want to set the destination Age (obviously). This is the Age filename, ie: as they appear in Uru's DAT folder. For instance, for Gahreesen you'd write Garrison, for Eder Kemo you'd write Garden, and so on.
You might also need to set the spawn point you want to link to. If you want it to link to the default spawn point (ie: LinkInPointDefault), remove the "value" line, and set the type to skip:
Code: Select all
- type: skip


As for the linking panel texture name, there are two ways to do it.
- create an object (anything... a box, a plane, whatever). Put this object out of sight, and apply your linking panel's texture to it (this will make sure the texture is exported. The object itself is unimportant). Then set the value to the name of this texture.
- you can also use "type: skip" to let the Offline-KI find a linking image. This linking image must be located in the "img" folder, with the naming convention "LinkingImage_AgeName.jpg" or "LinkingImage_AgeName_SpawnPointName.jpg".


Also, you might want to know about two more features you can use:
- using fakelink is possible. This is used to avoid reloading the whole Age, which might take long.
Simply replace the destination age name by "fakelink".
Note: fakelink does not reset the third person camera. If you don't want the camera to fly across your Age while linking, you must set up a camera region.

- setting "void" to the destination Age name will make the linking panel black and unclickable, as if it was broken.





Blender - Creating Linking Books:

Alright, now that you set up a bahro stone, let's create a linking book !

Setup your book and region objects like you did for your bahro stone.

Here is the AlcScript:


Code: Select all
<book object name>:
    physical:
        pinned: true
    logic:
        modifiers:
            - tag: click
              cursor: poised
              flags:
                - localelement
              activators:
                - type: objectinvolume
                  remote: <region name>
                  triggers:
                    - any
              conditions:
                - type: activator
                  activators:
                      - type: picking
                - type: objectinbox
                  satisfied: true
              actions:
                - type: pythonfile
                  ref: $click
        actions:
            - type: pythonfile
              tag: click
              pythonfile:
                file: xSimpleLinkingBook
                parameters:
                    # activator: clickable object
                    - type: activator
                      ref: logicmod:<book object name>_click
                   
                    # destination Age filename (skip will make this a book to Nexus)
                    - type: string
                      value: <age name>
                   
                    # name of spawn point to link to (skip to link to default link in point)
                    - type: string
                      value: <sp name>
                   
                    # name of linking panel texture (skip to let the script find one for you)
                    - type: string
                      value: <texture name>
                   
                    # name of the book's cover texture (skip to show open. Only works if you set your own linking panel texture)
                    - type: string
                      value: <texture name>
                   
                    # stamp/image on the left page (skip to show none)
                    - type: string
                      value: xGoWStamp
                   
                    # stamp/img X pos
                    - type: int
                      value: 150
                   
                    # stamp/img Y pos
                    - type: int
                      value: 110
                   
                    # book X scale
                    - type: float
                      value: 1.0
                   
                    # book Y scale
                    - type: float
                      value: 1.0



As you can see, it looks a bit like the Bahro stone AlcScript. You'll even recognise these parameters:

Code: Select all
# activator: clickable object
- type: activator
  ref: logicmod:<book object name>_click

# destination Age filename (skip will make this a book to Nexus)
- type: string
  value: <age name>

# name of spawn point to link to (skip to link to default link in point)
- type: string
  value: <sp name>

# name of linking panel texture (skip to let the script find one for you)
- type: string
  value: <texture name>


You should already know how to use them :)

Code: Select all
# name of the book's cover texture (skip to show open. Only works if you set your own linking panel texture)
- type: string
  value: <texture name>


If you want the linking book to be closed when you click it so you can admire the book cover's, you must provide the name of the texture that will be used.
The texture MUST be included in the PRP by applying it to an object in the scene (the same method you use with Linking Panels).
Note: because of some problem with Plasma, if you use this, you MUST also set your own linking panel texture (you can't use one in the img folder).


Code: Select all
# stamp/image on the left page (skip to show none)
- type: string
  value: xGoWStamp


This allows you to put a stamp or an image on the left page of the linking book. xGoWStamp is the GoW stamp by CalumTraveler.
If you want to use your own stamp texture, you must include it in your PRP the same way you do with linking panels and book covers.


Code: Select all
# stamp/img X pos
- type: int
  value: 150

# stamp/img Y pos
- type: int
  value: 110


These control the image position on the book. (0,0) is the top left-hand corner.
These two values are defaulted to (150,110) for the GoW stamp.


Code: Select all
# book X scale
- type: float
  value: 1.0

# book Y scale
- type: float
  value: 1.0


These two are the same as for journals.



Finally, the features you might want to use:
- fakelink and void link, as with Bahro Stones
- animated linking panels: if the linking panel texture name ends with .bik, the script will automatically load a bink file from the AVI folder (for instance: direboWithAlpha.bik).
Keep in mind that animated linking panels don't work for everyone, though.





Plasma HTML

Alright, making a journal by simply writing text in a file is cool, but there are a few options available that you might want to know about.

These "parameters" just need to be written within the text for your journal.

They will always look like this:
Code: Select all
<name argument_1=value argument_2=value>

You don't need to write the arguments in a specific order. You don't need to write each argument if you need to modify only one either (just like regular HTML/XML).
For instance, you could write the above example:
Code: Select all
<name argument_2=value argument_1=value>
or
Code: Select all
<name argument_2=value>



Here are those I know, and that can be useful when writing journals:


Code: Select all
<cover src="xEditableJournalCover*1#0.hsm">

This defines the texture for the book cover. In this case, that's the editable journal you pick up on the Relto
You must put it only once at the beginning of your journal.
The texture must be included in your Age (just like linking panels, it must be applied as a texture to a random object out of sight), or be used by Cyan in another of their Ages.


Code: Select all
<margin left=62 right=62 top=48>

This defines the border in pixels at which the text is written.
IIRC, this works per-page and not per-line. Which means you cannot change the margin for a single line, but can change it for the full page.


Code: Select all
<font size=20 face=Courier color=400000>

This controls the font size and appearance.
Font files are located in the DAT folder, and all end with .p2f (Tahoma, Tricia, Yeesha, Arial...).
The color argument is the font color, written in hexadecimal.
For instance, 400000 is a dark red. 000000 is black, 00FF00 green, 0000FF blue, FFFFFF white, etc.


Code: Select all
<pb>

Page break, it takes no argument.


Code: Select all
<p align=center>

Controls where the text is written on the page. In this case it's centered, you can also use "left" or "right"


Code: Select all
<img src="xlinkpanelblackvoid*1#0.hsm" opacity=0.7 align=center blend=alpha>

Puts an image on the page. It can be useful when you want to add a drawing, a stamp, whatever.
Opacity is the image blending.
blend=alpha is most commonly used when your image has an alpha layer.
The texture must be included in your Age (just like linking panels, it must be applied as a texture to a random object out of sight).


Code: Select all
<movie src="avi\DireboWithAlpha.bik" align=center blend=alpha>

It's the same as <img>, except it loads a bink file instead of a texture.
It is not recommended to use it, since it crashes the game for some players.
Usually it's used for animated linking panels.



3DsMax

If you're using 3DsMax, you'll need to download the source of the script.
These can be found on the Offline-KI's gitorious page
You must download:
- offline-ki/xLinkMgr.py
- offline-ki/xSimpleJournal.py
- offline-ki/xSimpleBahroStone.py
- offline-ki/xSimpleLinkingBook.py
- misc/booksDustGlobal.py

You should have a folder set by the Max plugin with all the Python scripts used by Cyan - put the .py files you downloaded in it.

Note: you might have to edit a line in the three xSimple....py script to have them show up in Max. Open them with any regular text editor, find "self.id = -1", and replace -1 by a high enough number. Each script must have a unique number, so since Cyan already used a lot of these numbers, you might want to try something above 6000.


Now, you must create a book object and a clickregion, in which this book will be clickable by the avatar (I'm not sure how you set it up in Max). When the book is clicked, it must notify a Python script: xSimpleJournal, xSimpleBahroStone or xSimpleLinkingBook depending of what you need to create.
There should be a few options boxes to fill. What each of them do is detailed under the AlcScript of each Blender versions.




About images in Max:
It's a bit more tricky, because the Max plugin has some crazy naming convention for textures. For instance, if you have a texture named "mytexture.png", the plugin might rename it something like "mytexture*0#0.hsm".
The best way to know the texture's name is to open dat/<YourAge>_district_Textures.prp in PRPShop. This will list all textures in the Age, with their exact name.
Last edited by Sirius on Fri Sep 05, 2014 1:56 am, edited 3 times in total.
User avatar
Sirius
 
Posts: 1078
Joined: Mon Jul 26, 2010 4:46 am
Location: France

Re: Tutorial: simple journals and Linking Books

Postby tachzusamm » Mon Aug 05, 2013 7:49 am

Great. Well done, Sirius.
Your work is much appreciated. And it's a nice tutorial; all you need to know about using it.

Put a cross-link in the Wiki to this thread, maybe? Sometimes useful posts get lost in nirvana after half a year has passed - or even sooner.
User avatar
tachzusamm
 
Posts: 575
Joined: Thu May 29, 2008 2:03 am
Location: Germany

Re: Tutorial: simple journals and Linking Books

Postby diafero » Mon Aug 05, 2013 8:19 am

Btw, the new Offline KI with these scripts included got released yesterday, so you can now easily use the scripts on your ages :)

tachzusamm wrote:Put a cross-link in the Wiki to this thread, maybe? Sometimes useful posts get lost in nirvana after half a year has passed - or even sooner.

I will add a link from the Offline KI documentation. Probably the correct thing to do would be to put the tutorial themselves into the wiki, with the appropriate categories etc., so they can be found like the others.
I prefer e-mails to "diafero arcor de" (after adding the at and the dot) over PMs.

"Many people's horizon is a circle with a radius of zero. They call it their point of view."

Deep Island Shard | Offline KI
diafero
Deep Island Admin
 
Posts: 2803
Joined: Mon May 05, 2008 5:50 am
Location: Germany

Re: Tutorial: simple journals and Linking Books

Postby Karkadann » Sat Jan 25, 2014 7:17 pm

now, on to writing your journal...
In Uru's folder, you'll see a directory called "ageresources". Create a new text file in it, name it <YourAge>--<journal name>.txt (minus the <> symbols)
Then, simply write your journal in it

I could not find a ageresources folder so I made one put the text file in it linked in found a real cool looking Uru book opened it and got a an error message instead of the journal text
This book could not be found
Make sure the file ageresources TestEx--Journal.txt
exist or that the game has access to it.


How do I get the game to recognize the ageresources folder and the txt file in it

Thanks in advance

Edit to add.

Never mind, It was an operator malfunction I didn't label the text file properly
Now you know where I got the idea for my signature from :D

Btw it works great in Max as well
Now im gonna try the other options
"It is the responsibility of every student to try and surpass there teacher"
Sorry teach a Bahro ate my homework again
User avatar
Karkadann
 
Posts: 1219
Joined: Sun Aug 02, 2009 10:04 am
Location: Class Clown University

Re: Tutorial: simple journals and Linking Books

Postby Sirius » Sun Jan 26, 2014 3:25 am

Glad to hear it's working fine now !


Karkadann wrote:Now you know where I got the idea for my signature from :D
Haha ! It reminds me that there are three kind of problems with computers sciences:
- software bugs
- hardware bugs
- chair-computer interface problems... This interface is located between your chair and your computer's monitor... :P

I tried once to tweak the Python file for the Relto bookshelf. When I launched the game, it didn't behave as I expected. I spent 1 hour looking through 1800 code lines to find what went wrong. In the end, I simply realised I named the file psnlBookShelf.py instead of psnlBookshelf.py...
User avatar
Sirius
 
Posts: 1078
Joined: Mon Jul 26, 2010 4:46 am
Location: France

Re: Tutorial: simple journals and Linking Books

Postby Karkadann » Sun Jan 26, 2014 10:17 am

the simple journal python works great as do the various other options Ive tried so far but I can not seem to get the Simple Bahro Stone and the Linking Book pythons to show up in the drop down menu.

I often wondered what it is in a python file that decides whether or not it shows up in the drop down menu
"It is the responsibility of every student to try and surpass there teacher"
Sorry teach a Bahro ate my homework again
User avatar
Karkadann
 
Posts: 1219
Joined: Sun Aug 02, 2009 10:04 am
Location: Class Clown University

Re: Tutorial: simple journals and Linking Books

Postby Sirius » Sun Jan 26, 2014 11:14 am

Ah, I must have forgotten to update the id parameter... I never understood the use of this damn thing (is there any at all ?)

If I remember correctly, when using it in Max, you have to put the decompiled Python script (<somename>.py) into a specific folder, right ? Open the Python files in a text editor, search for something like this:
Code: Select all
    def __init__(self):
        ptResponder.__init__(self)
        self.id = -1
        self.version = 1
Replace -1 for self.id by any value, until it shows up in Max.
User avatar
Sirius
 
Posts: 1078
Joined: Mon Jul 26, 2010 4:46 am
Location: France

Re: Tutorial: simple journals and Linking Books

Postby Karkadann » Mon Jan 27, 2014 12:23 am

iv tried quite a few numbers and none of them seem to work, what am I doing wrong??
"It is the responsibility of every student to try and surpass there teacher"
Sorry teach a Bahro ate my homework again
User avatar
Karkadann
 
Posts: 1219
Joined: Sun Aug 02, 2009 10:04 am
Location: Class Clown University

Re: Tutorial: simple journals and Linking Books

Postby Tsar Hoikas » Mon Jan 27, 2014 9:42 am

Sirius wrote:Ah, I must have forgotten to update the id parameter... I never understood the use of this damn thing (is there any at all ?)


It's used by the max plugin for bookkeeping.
Image
User avatar
Tsar Hoikas
Councilor of Technical Direction
 
Posts: 1833
Joined: Fri Nov 16, 2007 9:45 pm
Location: South Georgia

Re: Tutorial: simple journals and Linking Books

Postby Karkadann » Mon Jan 27, 2014 2:00 pm

Im gonna assume that every python file needs its own self id #, now Im not that good with odds however the sheer number of pythons that already have numbers seriously reduces the chances of picking a number that will work.
so im wondering is their any other way of forcing the python to show up in the drop-down menu or is it only a matter of playing the Python self id # lottery until I win

I also noticed that none of the pythons from the moul-scripts-master of the H-uru/moul-scripts GitHub show up in the drop down menu
"It is the responsibility of every student to try and surpass there teacher"
Sorry teach a Bahro ate my homework again
User avatar
Karkadann
 
Posts: 1219
Joined: Sun Aug 02, 2009 10:04 am
Location: Class Clown University

Next

Return to Scripting

Who is online

Users browsing this forum: No registered users and 2 guests