Tutorial: simple journals and Linking Books
Posted: 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:
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:
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.
<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).
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.
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 esHTML.
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:
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:
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:
As you can see, it looks a bit like the Bahro stone AlcScript. You'll even recognise these parameters:
You should already know how to use them
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).
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.
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.
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 esHTML
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.
EDIT: Please refer to this better Wiki article instead !
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.
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 esHTML.
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 esHTML
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.
EDIT: Please refer to this better Wiki article instead !
- outdated post Show Spoiler
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.