Difference between revisions of "Offline KI:Age Writer Tutorials"

(Adding a book to the shelf: update for 3.8)
(Adding ages (using age descriptors): add lastUpdate jey)
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
This page contains the technical documentation of the Offline KI. For more information and instructions, go back to the [[Offline KI|Offline KI main page]].
+
{{Tutorial}}
  
==Adding ages ==
+
This page contains some tutorials for the Offline KI which are interesting for age writers. For more information and instructions, go back to the [[Offline KI|Offline KI main page]].
  
''Note: This information applies to the soon to be released Offline KI 3.8 and above only''
+
== Adding ages (using age descriptors) ==
  
 
In order to add an age to the Offline KI, you have to create an age descriptor and put into the folder "img\AgeInfo" in your Uru installation. That folder is loaded by the Offline KI to learn about fan-ages and what to show in Nexus. The Offline KI will also add all ages it does not know, but of course it doesn't know the real name of the age then (which is usually different from the filename), so it marks them as "unknown age".
 
In order to add an age to the Offline KI, you have to create an age descriptor and put into the folder "img\AgeInfo" in your Uru installation. That folder is loaded by the Offline KI to learn about fan-ages and what to show in Nexus. The Offline KI will also add all ages it does not know, but of course it doesn't know the real name of the age then (which is usually different from the filename), so it marks them as "unknown age".
Line 10: Line 10:
  
 
  displayName=My Age
 
  displayName=My Age
  showIn=none
+
  lastUpdate=2014-04-25
 +
description=My first age, and an age descriptor demo.\nThis will be shown on a new line.
  
This tells Uru that the user-visible name for the age is "My Age", and that it should not be shown in Nexus. If you omit the last line, the age will appear in the "Restoration Links" category in Nexus.
+
This tells Uru that the user-visible name for the age is "My Age", and when the age has been last updated. The latter information is used by the Offline KI to fill parts of the Shelf, and to sort the list of ages in the Nexus.
 +
The example also gives a short description which will be displayed at the bottom of the Nexus GUI and in Relto shelf books linking to your age. A newline in the description is encoded as "\n".
 +
 
 +
Per default, the age will be shown in the "Restoration Links" in Nexus. If you want to hide your age (for example because it is a reward which can be reached from another age after solving a puzzle), add a new line saying
 +
 
 +
showIn=none
  
 
== Adding a book to the shelf ==
 
== Adding a book to the shelf ==
Line 24: Line 30:
  
 
where "InternalName" is the name of the age file (without .age), and "SpawnPointName" is the name of the spawn point you want to arrive at. If you leave it out, the game will choose the default spawn point. You can add several links to a book by adding several lines to it's section, just make sure each age also has a valid age descriptor (see above). The age descriptor is also used to add a description on the left page, below your age's name.
 
where "InternalName" is the name of the age file (without .age), and "SpawnPointName" is the name of the spawn point you want to arrive at. If you leave it out, the game will choose the default spawn point. You can add several links to a book by adding several lines to it's section, just make sure each age also has a valid age descriptor (see above). The age descriptor is also used to add a description on the left page, below your age's name.
 +
 +
Please note that any changes to ULMServerLinkBook.inf will be overwritten on the next upgrade of the Offline KI. To prevent your changes from getting lost, rename the file to ULMLinkBook.inf - if the Offline KI can not find the file it usually uses, it will fall back to using that one. The next upgrade of the Offline KI will install ULMServerLinkBook.inf again, which you then just have to remove to get your custom shelf back.
  
 
== Adding a linking panel ==
 
== Adding a linking panel ==
Line 42: Line 50:
  
 
This will load the cover from CoverImage_MyAgeName.jpg.
 
This will load the cover from CoverImage_MyAgeName.jpg.
 +
 +
== Python scripts to be used in fan ages ==
 +
 +
The Offline KI contains some Python scripts which you can use in your age, so that you have less (or no) Python scripting to do yourself. If a script here suits your needs, it is encouraged you make use of it - this reduces the overall amount of scripts and common programming mistakes, and it lets your age automatically benefit from future fixes to the scripts.
 +
 +
* [http://forum.guildofwriters.org/viewtopic.php?f=9&t=6197 Linking books, Bahro stones and journals]
 +
* [[SimplePanel|Simple Control Panels]]
 +
* [[MultiDialogToggle|Sequence of dialog GUIs]]
 +
* Undocumented: xDynamicPanel, xMoviePlayer, xAgeSDLBoolTagRespond, xRandomResp

Revision as of 10:46, 11 May 2014

Disambig gray.png

This is a tutorial page.
 

This page contains some tutorials for the Offline KI which are interesting for age writers. For more information and instructions, go back to the Offline KI main page.

Adding ages (using age descriptors)

In order to add an age to the Offline KI, you have to create an age descriptor and put into the folder "img\AgeInfo" in your Uru installation. That folder is loaded by the Offline KI to learn about fan-ages and what to show in Nexus. The Offline KI will also add all ages it does not know, but of course it doesn't know the real name of the age then (which is usually different from the filename), so it marks them as "unknown age".

An age descriptor is a simple text file. The filename must exactly match the filename of your age, followed by ".txt". So, if your age file is called "My_Age.age", call the age descriptor "My_Age.txt". A simple example descriptor looks as follows:

displayName=My Age
lastUpdate=2014-04-25
description=My first age, and an age descriptor demo.\nThis will be shown on a new line.

This tells Uru that the user-visible name for the age is "My Age", and when the age has been last updated. The latter information is used by the Offline KI to fill parts of the Shelf, and to sort the list of ages in the Nexus. The example also gives a short description which will be displayed at the bottom of the Nexus GUI and in Relto shelf books linking to your age. A newline in the description is encoded as "\n".

Per default, the age will be shown in the "Restoration Links" in Nexus. If you want to hide your age (for example because it is a reward which can be reached from another age after solving a puzzle), add a new line saying

showIn=none

Adding a book to the shelf

Note: If you just want to quickly reach your own age because you are working on it, the best way to do so (even quicker than using the shelf) is to type "/link InternalName" as soon as you arrive on Relto. This will directly bring you to the default link-in-point. Alternatively, use "/linksp InternalName SpawnPointName" to link to a different link-in-point. To automatically link to your age when Uru starts, type "/autolink InternalName".

However, if you really want to add an age to the Relto Shelf, open the ULMServerLinkBook.inf file. You see a bunch of [Book] sections, each corresponding to a book shown in your Relto. Each section can either define its position, like [Book 4], or automatically use the book to the right of the previously defined one if the number is omitted. Below the section header, you can define the cover of the book and as many pages as you want. The most basic book, offering a single link to a single age, looks like this:

[Book]
age:InternalName[,SpawnPointName]

where "InternalName" is the name of the age file (without .age), and "SpawnPointName" is the name of the spawn point you want to arrive at. If you leave it out, the game will choose the default spawn point. You can add several links to a book by adding several lines to it's section, just make sure each age also has a valid age descriptor (see above). The age descriptor is also used to add a description on the left page, below your age's name.

Please note that any changes to ULMServerLinkBook.inf will be overwritten on the next upgrade of the Offline KI. To prevent your changes from getting lost, rename the file to ULMLinkBook.inf - if the Offline KI can not find the file it usually uses, it will fall back to using that one. The next upgrade of the Offline KI will install ULMServerLinkBook.inf again, which you then just have to remove to get your custom shelf back.

Adding a linking panel

The Offline KI looks for linking panels in the following order: For Relto links, it first looks for videos in the "avi" directory: If "InternalName_SpawnPointName.bik" exists, that file is used. The same goes for "InternalName.bik". Only if both of them do not exists, it looks for static linking images - it tries to read "LinkingImage_InternalName_SpawnPointName.jpg" in the "img" directory. If that file does not exist, it tries "LinkingImage_InternalName.jpg" in the same directory. If that file doesn't exist either, it uses the default panel, the black void. In Nexus, it uses the same procedure without taking videos into account and with "LinkInPointDefault" as SpawnPointName.

To create a linking image for your age, first of all you need a screenshot of what it should show. Then use GIMP or a similar application to first crop the image to 1280x814 (or 800x509 or 640x408 or other resolutions with the same aspect ratio) and then scale it to 410x168 pixel - yes, that stretches it. The scaling is not mandatory, the game will do it for you if you don't do it, but panels shown in books usually look better when you do the scaling with proper interpolation. After the picture has the right format, save it with the appropriate name and in jpg format (see above) in the "img" directory - done!

Adding a custom book cover

For the mapping of the cover in your Relto to be correct, you have to use exactly the right positions of the elements that make up a book: The cover has to have a size of 128x292 pixel, with the top left corner being at 22,105 and the bottom right at 150,397. The full size of the picture always has to be 512x512 pixel, and it has to be saved as jpg file. Of course, it is always a good idea to have a look at other covers and use them as template. Rainforce created the following test cover which shows the parts of the images used for spine and front. It also contains the top and bottom side, which usually is not changed - but you can do so, if you wish. Click the image to enlarge it.

Test cover
red: spine, green: front
The 4px part they BOTH share is really strange, and don't forget about the fact that the sides of the spine are "leaning" (load this image as cover to see for yourself)


To have a book show your cover, put the following line into the part of the ULMServerLinkBook.inf file which sets your book (the best place is right after "[Book <nr>]"):

cover:MyAgeName

This will load the cover from CoverImage_MyAgeName.jpg.

Python scripts to be used in fan ages

The Offline KI contains some Python scripts which you can use in your age, so that you have less (or no) Python scripting to do yourself. If a script here suits your needs, it is encouraged you make use of it - this reduces the overall amount of scripts and common programming mistakes, and it lets your age automatically benefit from future fixes to the scripts.