Difference between revisions of "ZLZ Age Importer"

m (Warn about importing from a protected folder)
m (Add warning about MQO/HexIsle files)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
  
On occasion, it may be useful to import ages (made by Cyan or others) into Blender from PRP or AGE files. Importing an age allows a new Writer to become familiar with how an age is constructed before it is exported into Uru. It may also be useful to retired Writers who have deleted (a) BLEND file(s) for their age and wish to continue development of that age.
+
On occasion, it may be useful to import ages (made by Cyan or others) into Blender from PRP or AGE files. Importing an age allows you to use Cyan's assets into your own Ages; become familiar with how Ages are constructed; or even work on an Age for which you don't have the BLEND file.
  
Previously, Age importing was done using the [[PyPRP Age Importer]]. However this version has several issues (mainly running on an old version of Blender and the PRP library), and was discontinued.
+
This is where the Zero-Length-Zenith importer ("ZLZ" for short) comes in.
The new Zero-Length-Zenith importer ("ZLZ" for short) was rewritten from scratch and designed to run on Blender 2.7x. It is slightly more stable than the PyPRP importer, and thus might be a better choice than PyPRP.
+
  
NOTE: while this plugin allows you to import Ages, it doesn't mean re-exporting them is possible. Clickables, sounds and the like aren't imported. Also, keep in mind that the imported assets aren't yours: they are still Cyan's/whoever is the author, and should be treated as such.
+
Keep in mind: imported Ages cannot be immediately re-exported. There will be some manual fixing to do.
 +
Also, assets you import are still owned by either Cyan, or the person who made the Age. You are however totally allowed to reuse Cyan's assets in your own Ages running on Uru's engine.
  
==Required Software==
+
Furthermore, neither MagiQuest Online nor HexIsle data will import correctly using ZLZ - you will need to convert their files using [[Drizzle#Cyan_age_conversion|Drizzle]] first, then run ZLZ on the result. Crowthistle on the other hand can be imported as-is without converting it first.
 
+
ZLZ's only requirement is the [[Korman]] plug-in (ZLZ actually relies on the HSPlasma library for loading Ages, which is distributed with all versions of Korman).
+
  
 
== Installation ==
 
== Installation ==
  
Download the [https://www.dropbox.com/s/rkk77tordxa8ir1/zero_length_zenith.zip?dl=1 ZLZ zip file]. Then in Blender, go to the User Preferences panel (Ctrl+Alt+U), switch to the Add-ons tab, and click "Install Add-On from File...". Select the ZIP you just downloaded. Remember to activate it by ticking its checkbox, and you're done !
+
ZLZ requires the [[Korman]] plug-in. Make sure you install it before installing ZLZ.
 +
 
 +
Then, download the [https://gitlab.com/JriusUru/zero-length-zenith/-/archive/master/zero-length-zenith-master.zip ZLZ zip file], and extract its contents. Browse to <code>%APPDATA%\Blender Foundation\Blender\<version number>\scripts\addons</code>, and inside it, paste the zero_length_zenith folder (which contains <code>__init__.py</code>, etc).
 +
Alternatively, you can instead install it in <code>C:\Program Files\Blender Foundation\Blender\2.79\scripts\addons</code>. Whichever you prefer, as long as it's not both.
 +
 
 +
Now, in Blender, go to the User Preferences panel (Ctrl+Alt+U), switch to the Add-ons tab. Search "zero", and activate the plugin. Remember to click "Save User Settings".
 +
 
 +
While you're on this tab, you may want to edit the "MOUL source textures" path. If you have cloned the [https://github.com/H-uru/moul-assets MOUL assets Git repository], you may point it to the location of the <code>/moul-assets/sources/textures/tga</code> folder. This allows ZLZ to load the higher-quality original textures instead of the lower-quality ones from the PRPs.
 +
Note that this is entirely optional, so if you have no idea what repositories/Git are, you may skip this for simplicity.
  
 
== Usage ==
 
== Usage ==
Line 20: Line 26:
 
=== Importing an Age or PRP file ===
 
=== Importing an Age or PRP file ===
  
This is rather straightfoward. Once the plugin is installed and enabled, delete all existing objects in your scene (otherwise they won't be automatically removed), then select <code>File → Import → ZLZ Uru Importer</code>. You can now select the .age or .prp file you want to import.
+
This is rather straightfoward. Once the plugin is installed and enabled, select <code>File → Import → ZLZ Uru Importer</code>. You can now select the .age or .prp file you want to import.
  
 
Note that if Uru is installed in the "C:\Program Files" folder, you will need to either run Blender as administrator, or copy the AGE, FNI and PRP files you want to import to another folder with write permissions (such as your Documents folder). Otherwise you will run into a "Permission Denied" error, as the importer needs to extract a few files to that location.
 
Note that if Uru is installed in the "C:\Program Files" folder, you will need to either run Blender as administrator, or copy the AGE, FNI and PRP files you want to import to another folder with write permissions (such as your Documents folder). Otherwise you will run into a "Permission Denied" error, as the importer needs to extract a few files to that location.
Line 28: Line 34:
 
=== What to expect from the results ===
 
=== What to expect from the results ===
  
As previously mentioned, ZLZ doesn't import all there is in the PRP - it mostly focuses on visuals like meshes and textures. It's also worth noting Plasma and Blender have very different behaviors, so lots of data simply don't cross over the two softwares correctly.  
+
As previously mentioned, ZLZ doesn't import all there is in the PRPs, because of how vastly different Blender/Korman are compared to Plasma.
Here is a small list of things that are worth knowing about the importer:
+
If you really intend to re-export the Age, it might be useful to learn how to use PrpShop (available when you install [https://guildofwriters.org/wiki/PlasmaShop PlasmaShop]). PrpShop is not for the faint of heart as it allows you to dig into the complex PRP format, but can help you figure out what ZLZ fails to import.
* The currently active Blender scene will display the whole Age. But all "pages" (=PRP files) are also duplicated on other Blender scenes.
+
 
* Objects are sorted on various layers depending on their type. Visual objects are generally on the first layer, colliders on the second, regions on the third, empties on the fourth, and so on.
+
Also, here is a small list of things that are worth knowing about the importer:
 +
* The currently active Blender scene will display the whole Age. But all "pages" (=PRP files) are also duplicated on other Blender scenes (mostly just for convenience).
 +
* Objects are sorted on various layers depending on their type. Visual objects are generally on the first layer, colliders on the second, regions on the third, and so on.
 
* ZLZ will do its best to mimic Plasma materials, however there are some cases where it's simply impossible to do properly. In this case, it will recolor the incorrect material so it's easier to identify:
 
* ZLZ will do its best to mimic Plasma materials, however there are some cases where it's simply impossible to do properly. In this case, it will recolor the incorrect material so it's easier to identify:
 
** Purple materials means some layer combination failed to import (or ZLZ didn't understand it)
 
** Purple materials means some layer combination failed to import (or ZLZ didn't understand it)
Line 37: Line 45:
 
** Cyan materials are a combination of purple and yellow materials.
 
** Cyan materials are a combination of purple and yellow materials.
 
** Dark green materials means the material itself simply couldn't be found, and may be located in another PRP.
 
** Dark green materials means the material itself simply couldn't be found, and may be located in another PRP.
* Objects using transparent materials are also displayed in wireframe, to prevent them from being completely invisible.
+
 
 +
=== Video tutorial ===
 +
 
 +
Calum Traveler made a [https://www.youtube.com/watch?v=jjj-rBtLzlA video] which, among other things, shows how to use ZLZ to import an Age.
  
 
== Reporting bugs ==
 
== Reporting bugs ==
Line 46: Line 57:
  
 
ZLZ has a [https://gitlab.com/JriusUru/zero-length-zenith Git repo on Gitlab], if you're interested.
 
ZLZ has a [https://gitlab.com/JriusUru/zero-length-zenith Git repo on Gitlab], if you're interested.
 +
 +
== Older stuff ==
 +
 +
Previously, Age importing was done using the [[PyPRP Age Importer]]. It should be considered obsolete, as ZLZ is now vastly superior.

Latest revision as of 08:29, 10 July 2022

Introduction

On occasion, it may be useful to import ages (made by Cyan or others) into Blender from PRP or AGE files. Importing an age allows you to use Cyan's assets into your own Ages; become familiar with how Ages are constructed; or even work on an Age for which you don't have the BLEND file.

This is where the Zero-Length-Zenith importer ("ZLZ" for short) comes in.

Keep in mind: imported Ages cannot be immediately re-exported. There will be some manual fixing to do. Also, assets you import are still owned by either Cyan, or the person who made the Age. You are however totally allowed to reuse Cyan's assets in your own Ages running on Uru's engine.

Furthermore, neither MagiQuest Online nor HexIsle data will import correctly using ZLZ - you will need to convert their files using Drizzle first, then run ZLZ on the result. Crowthistle on the other hand can be imported as-is without converting it first.

Installation

ZLZ requires the Korman plug-in. Make sure you install it before installing ZLZ.

Then, download the ZLZ zip file, and extract its contents. Browse to %APPDATA%\Blender Foundation\Blender\<version number>\scripts\addons, and inside it, paste the zero_length_zenith folder (which contains __init__.py, etc). Alternatively, you can instead install it in C:\Program Files\Blender Foundation\Blender\2.79\scripts\addons. Whichever you prefer, as long as it's not both.

Now, in Blender, go to the User Preferences panel (Ctrl+Alt+U), switch to the Add-ons tab. Search "zero", and activate the plugin. Remember to click "Save User Settings".

While you're on this tab, you may want to edit the "MOUL source textures" path. If you have cloned the MOUL assets Git repository, you may point it to the location of the /moul-assets/sources/textures/tga folder. This allows ZLZ to load the higher-quality original textures instead of the lower-quality ones from the PRPs. Note that this is entirely optional, so if you have no idea what repositories/Git are, you may skip this for simplicity.

Usage

Importing an Age or PRP file

This is rather straightfoward. Once the plugin is installed and enabled, select File → Import → ZLZ Uru Importer. You can now select the .age or .prp file you want to import.

Note that if Uru is installed in the "C:\Program Files" folder, you will need to either run Blender as administrator, or copy the AGE, FNI and PRP files you want to import to another folder with write permissions (such as your Documents folder). Otherwise you will run into a "Permission Denied" error, as the importer needs to extract a few files to that location.

The import option File → Import → ZLZ texture extractor is also available. This batch extracts ALL the textures from Uru's DAT folder, which may be useful in some cases.

What to expect from the results

As previously mentioned, ZLZ doesn't import all there is in the PRPs, because of how vastly different Blender/Korman are compared to Plasma. If you really intend to re-export the Age, it might be useful to learn how to use PrpShop (available when you install PlasmaShop). PrpShop is not for the faint of heart as it allows you to dig into the complex PRP format, but can help you figure out what ZLZ fails to import.

Also, here is a small list of things that are worth knowing about the importer:

  • The currently active Blender scene will display the whole Age. But all "pages" (=PRP files) are also duplicated on other Blender scenes (mostly just for convenience).
  • Objects are sorted on various layers depending on their type. Visual objects are generally on the first layer, colliders on the second, regions on the third, and so on.
  • ZLZ will do its best to mimic Plasma materials, however there are some cases where it's simply impossible to do properly. In this case, it will recolor the incorrect material so it's easier to identify:
    • Purple materials means some layer combination failed to import (or ZLZ didn't understand it)
    • Yellow materials means a layer has a rotation component, which means a UV channel needs to be rotated in order for its texture to show up correctly. The rotation amount is stored as a custom property at the end of the Texture panel in the Property Editor.
    • Cyan materials are a combination of purple and yellow materials.
    • Dark green materials means the material itself simply couldn't be found, and may be located in another PRP.

Video tutorial

Calum Traveler made a video which, among other things, shows how to use ZLZ to import an Age.

Reporting bugs

Feel free to report bugs or discuss the plugin in the forum or on the dedicated thread.

Sources

ZLZ has a Git repo on Gitlab, if you're interested.

Older stuff

Previously, Age importing was done using the PyPRP Age Importer. It should be considered obsolete, as ZLZ is now vastly superior.