PDF Manual - Daggerfall Workshop

Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Daggerfall Tools for Unity
Thank you for downloading Daggerfall Tools for Unity. This asset is an API and suite of editor scripts
for procedurally importing Daggerfall’s content into Unity.
Getting Started
Before using Daggerfall Tools for Unity, you will need the following:
1. A full install of Daggerfall. You can download Daggerfall for free from the following sites.
http://www.elderscrolls.com/daggerfall/
http://www.uesp.net/wiki/Daggerfall:Files
2. Unity 4.5 or later (Free or Pro).
http://unity3d.com/unity/download
3. Optional, but highly recommended is Daggerfall Modelling. This Windows-only exploring
tool allows you to quickly search for and browse Daggerfall models, blocks, and locations. It
will be very useful until similar search features are implemented in Daggerfall Tools for
Unity.
http://www.dfworkshop.net/?page_id=1045 (Download).
https://code.google.com/p/daggerfallconnect/wiki/DaggerfallModelling (Online Manual).
Note: Also install Daggerfall Modelling prerequisites as described in online manual link.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Using Daggerfall Tools for Unity
Importing Asset
After installing Daggerfall and Unity3D, the next step is to import the latest Daggerfall Tools for Unity
package.
1. Open Unity3D and start a new project.
2. Click Assets > Import Package > Custom Package. Browse to the “Daggerfall Tools for Unity
– Release 2.unitypackage” file and click Open. This will import into your Asset folder and
compile scripts.
3. Alternatively double-click the .unitypackage file to install into your current project.
Prepare GameObject
Daggerfall Tools for Unity uses a singleton class to interface with the DaggerfallConnect API. Only
one instance of this script is required to import Daggerfall content from the editor or in code.
1. Create a new GameObject by clicking GameObject > Create Empty. Rename the new
GameObject to “DaggerfallUnity”.
2. Select your new DaggerfallUnity object in the Hierarchy then click Add Component in the
Inspector. Browse to Scripts > Daggerfall Workshop > Daggerfall Unity to add the main
script and any prerequisites.
3. Alternatively there is a prefab DaggerfallUnity in the Prefabs sub-folder, and a ready-made
empty scene in the Scenes sub-folder.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Set Arena2 Path
Before importing Daggerfall content, you must direct the script to your Daggerfall installation’s
Arena2 folder.
1. Click on your DaggerfallUnity game object. Use the Inspector to Browse for your Arena2
folder.
Importing Content
Once you have set your Arena2 path, go to the Importer (Beta) foldout in the Inspector of your
DaggerfallUnity instance. Currently, Daggerfall Tools for Unity does not have in-editor browsing. You
will find Daggerfall Modelling useful for locating IDs and names of content to import.
Models are imported using a unique ModelID. For example, ModelID 456 is the exterior of “Scourg
Barrow”.
Blocks are imported using a unique Block Name. City blocks end with .RMB and dungeon blocks end
with .RDB. For example, S0000999.RDB is the central block of Privateer’s Hold, and CUSTAA45.RMB
is the exterior of Castle Wayrest.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Cities and Dungeons are a little more involved as some locations have both an exterior map and a
dungeon map. To import a city or dungeon enter in the format RegionName/LocationName to either
the City field or Dungeon field.
For example, entering Daggerfall/Daggerfall in the City Name field will import the above-ground city
of Daggerfall. Entering the same into the Dungeon Name field will import the dungeons within Castle
Daggerfall. If the target location has any apostrophes, be sure to enter exactly as shown in-game. For
example, entering Daggerfall/Privateer’s Hold into the dungeon field will spawn Privateer’s Hold.
This field is also case-sensitive.
Once you have entered a model, block, or location, click the adjacent Import button to import that
resource into Unity.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Material Reader Options
The Material Reader is a required component of DaggerfallUnity. This script handles importing and
converting Daggerfall textures to Unity Materials. There are a few settings here that control how
materials are handled.








Atlas Textures. Combines billboards, ground textures, and animated textures into an atlas
for improved efficiency. Currently, animated textures must be atlased for animations to play.
It is recommended to always have this option enabled.
Compress Textures. Optionally enables lossy texture compression (DXT1 for textures
without alpha and DXT5 for textures with an alpha channel). As Daggerfall’s textures are
already very small, this option is only needed when you absolutely need to make a build as
small as possible. Otherwise recommended to leave disabled.
Compress Sky Textures. Enables texture compression just for sky textures. This setting will
always be considered enabled with Compress Textures checked.
Filter Mode. Change the desired filter mode of imported textures. The options are Point,
Bilinear, and Trilinear. This setting will be applied whenever materials are rebuilt, such as
when applying new climate settings.
Default Shader. This is the name of the shader applied to most materials imported from
Daggerfall. You can modify this to use your own shader instead. The shader is located using
Shader.Find() during import.
Billboard Shader. Same as above, but applied to billboard materials.
Self-Illumin Shader. Same as above, but applied to self-illuminated materials, such as the
windows.
Window Colour & Brightness. These options are for setting window colour and brightness
(from 0.0 to 1.0) for window styles. You can set individual options for Day, Night, Fog, and
Custom windows.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Mesh Reader Options
The Mesh Reader is another required component of DaggerfallUnity. This script handles import and
conversion of Daggerfall’s 3D models to Unity Mesh format. It also has several code helpers for
importing other types of mesh resources, such as properly scaled billboard quads and correctly tiled
ground planes. There are only a couple of options for Mesh Reader at this time.


Add Mesh Tangents. This option calculates tangents for Daggerfall models as they are
imported. Tangents are used for shaders requiring a Normal Map. It is recommended this
option is left enabled.
Add Lightmap UVs. This option creates a secondary UV channel, required for lightmapping
environments with tiling textures. Enabling this option will greatly increase import times. It’s
not recommended to use this option unless lightmaps are required.
Note: It is required to set these options prior to importing mesh data.
Daggerfall Unity Options
The DaggerfallUnity editor has several options available to control other details of importing
content.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Combining


Combine RMB. Combines models in RMB blocks (city blocks) to reduce draw calls and
increase efficiency of scene. Will otherwise maintain the same native scene layout as
Daggerfall. Only uncheck this option if you want to observe the exact scene layout Daggerfall
uses, or select individual models.
Combine RDB. Combines models in RDB blocks (dungeon blocks) as above.
Scene Options



Set Static Flags. Sets appropriate objects as static. Ignores billboards and dynamic objects.
Add Colliders. Adds a mesh collider to imported objects. Daggerfall’s meshes are very
simple, about the complexity of normal physics meshes.
RMB Door Triggers. Adds a BoxCollider to exterior building doors. This will be used in a
future release to transition in and out of building interiors. This will slightly increase import
times for large cities. Recommended to leave disabled until fully implemented.
Lights




Import Point Lights. Import point lights for cities and dungeons.
Animated. Not implemented. This will add a flickering range animation to point lights.
Tag. Set a custom tag for your lights. This enables you to modify/enable/disable scene lights
as required.
Custom Script. Add a custom MonoScript to each light. This enables you to attach custom
behaviour to your imported lights.
Enemies

Import Enemies. Imports fixed enemies in dungeons. This will be enhanced in a future
release.
Climate Textures
After importing a city location, you can customise the climate and season directly in the editor. To
get started, import a full city like Daggerfall/Daggerfall. By default this will have the climate settings
matching that location. Click on the DaggerfallCity game object in the Hierarchy.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Your Inspector then displays a summary of your location along with several controls for adjusting the
climate textures and window style.





Usage. Options are Disabled, Use Location, or Custom.
o Disabled. Turns off climate processing entirely.
o Use Location. Uses the location settings as shown in the About fields. Note that
resetting this component will currently destroy location metadata.
o Custom. Full control over which climate settings are applied.
Season. Options are Summer, Winter, Rain. Applies index modifiers to textures for
simulating different in-game seasons. The Winter setting will enable snow textures, and Rain
will slightly darken the ground plane.
Climate. Options are Desert, Mountain, Temperate, Swamp. Applies index modifiers for
simulating different in-game climates. Note that all climates fully support all seasons. For
example, Swamp+Winter does not have a full complement of snow textures.
Nature Flats. These are the trees, rocks, and shrubs used in combination with the climate.
You can set this however required, even in combinations not normally seen in-game.
Windows. Options are Disabled, Day, Night, Fog, Custom. Sets the window style of your city
location based on time of day and weather. Use the custom setting for unusual effects, and
set disabled to ignore window styles completely.
Above: A Winter scene with point lights and Night windows.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Dungeon Textures
You can manually set dungeon texture swaps via the Inspector when you have a dungeon selected.
Currently only the Custom option is implemented.
In brief, dungeon texture swaps work by modifying a table of base texture indices to a substituted
texture index. In-game, this is controlled by a random seed and random generator. Daggerfall Tools
for Unity currently does not implement authentic texture swaps based on location.
However it is possible to set your own custom swaps, or just click the Random button to generate a
new valid texture table at random. Be careful with custom swaps, as it’s possible to set an invalid or
inappropriate texture index. If you set an invalid swap, or just want to return back to start settings,
use the Reset button. Click Apply to apply your changes.
Quick Tips
Camera Setup & Billboards
The default DaggerfallBillboard.cs script for billboard sprites (enemies, trees, etc.) will rotate to face
the editor camera in your currently selected viewport while in edit mode.
After hitting play, sprites will look for the camera tagged “MainCamera” and rotate to face this
camera in the Game window. If you change the default camera, don’t forget to set the MainCamera
tag on your first-person camera.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Global Scale
Daggerfall’s 3D objects natively use fixed-point arithmetic. A straight conversion to floating point
results in very large environments well beyond the normal Unity 2m player height. By default,
everything is scaled to 1/40 of original size, which feels about right for a 1.75-2.0m high player.
If you would like to adjust the global scale play with GlobalScale field in MeshReader.cs. When
placing objects into the scene from code, don’t forget to multiply by GlobalScale so it will be aligned
with other objects in the scene. After changing GlobalScale, you will need to re-import content. It is
recommend to use the one scale throughout development.
First-Person Controller
Some of the architecture in Daggerfall is very steep. To ensure your first-person controller can
ascend stairs and ramps, try playing with the maximum slope and step height parameters. A
maximum slope of 75-80 degrees and a step height of 0.4-0.5 seems to work well in most cases.
You may also need to tune radius and height to ensure controller can fit through doors at bottom of
stairs and other tight spaces.
A free sample first-person controller is included for you to play with. This can be found in the Prefabs
folder. Simply delete your existing camera and drag the Player prefab into the scene, ensuring it is
positioned above the ground. When you hit play, you can explore your imported scene using WSAD
to move, SHIFT to toggle run, SPACE to jump, and ESC to uncaptured mouse.
Enemy Mobiles
Daggerfall Tools for Unity provides a foundation for enemy mobile units. These are spawned in when
starting a scene wherever the appropriate editor marker is found. You could extend this foundation
with spells, resistances, new enemy types, AI behaviours, and so on. Examples of enemy
implementation will be added in a future build.
Lighting
Billboards normal are currently set to half way between Vector3.up and Vector3.forward. This
means they will pick up some lighting from in front and some lighting from above. This seems to
work well for three-point lighting rigs and point lighting. If you find your billboards are too dark in
some orientations, add a cheap directional light to illuminate them a little.
In dungeons, change the light billboards to use an unlit material. This gives them a cheap selfilluminated look. In city scenes, the light is positioned directly above the light source and gives them
an overlit appearance. If this is not desirable, set to an unlit material like dungeons.
When using many point lights (common in cities) without benefit of Deferred Lighting from a Pro
license, you may need to increase the number of pixel lights available to your scene. Otherwise you
may find lights turning on and off at unexpected times in heavily lit areas. You can increase the Pixel
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Light Count in Unity from Quality settings. This will impact on performance, so Deferred is
recommended if you have a Pro license.
Standalone Builds
You can include files from the Arena2 folder in your build by appending “.bytes” to the file and
copying into a Resources folder in your Unity project. When loading files from the API with
FileUsage.UseMemory (now default) the FileProxy class will search your Resources folder for an
available file of the same name (e.g. “arch3d.bsa.bytes”) and use that file instead. This will help you
to create builds for web and mobile platforms.
Additional Notes
Following is a collection of other notes and bugs that may affect you while using this version of
Daggerfall Tools for Unity.






Editor GUI is currently limited and does not have location browsing/search features.
Dungeon textures cannot be set by location at this time.
Action records (moving platforms, switches, etc.) in dungeons are not implemented yet.
Once imported, everything is serialised in your scene file.
Meshes and materials are cached and shared where possible to reduce scene size and
improve efficiency. Starting and stopping play mode will clear cache as editor scripts are
reinitialised.
You can use any other Unity features on top of imported content. For example,
lightmapping, navigation, deferred rendering, etc.
Daggerfall Tools for Unity - Manual
v0.8.17 | 23/09/2014
Devblog
SVN
Twitter
Email
dfworkshop.net
code.google.com/p/daggerfall-unity
twitter.com/dfinterkarma
[email protected]
Patch Notes
0.8.17























Added DaggerfallBillboardEditor script for additional billboard details.
Added enumerations for enemy mobile types in dungeons (e.g. GiantBat, SkeletalWarrior).
Added DungeonType enumeration to DFRegion (e.g. Crypt, Orc Stronghold, Vampire Haunt,
etc.). Dungeon type is also displayed in Inspector when a dungeon is selected.
Added random encounter tables based on dungeon type.
Added animation support for atlased materials.
Added multi-facing enemy mobile billboard class.
Added enemy definitions for known enemy types.
Added animation groups for mobile units.
Added light import option for cities and dungeons.
Added enemy import options for dungeons.
Fixed minor RMB layout bug for non-combined city blocks.
Fixed minor billboard layout bug for city blocks.
Fixed minor ground plan tiling bug.
Fixed dungeon layout bug where RDB block positions on Z axis were reversed.
Fixed serialization bugs where native data is concerned. Unity does not like to serialize
unsigned values. Opted to create Unity-compatible structures where needed rather than
modify Daggerfall-native API structures. Removed [Serializable] flag from any API structs.
Moved MaterialReader and MeshReader to MonoBehaviour components on DaggerfallUnity
singleton.
Moved material and mesh import options to their respective reader component.
Moved all mesh loading to MeshReader and removed ModelFile class. This eliminated some
double-handling of data and slightly increased import times.
Added the ability to set preferred shader names on MaterialReader component. These are
located using Shader.Find() during import.
Added the ability to set window modifier colours and brightness on MaterialReader
component. This includes a custom window style option.
When loading Daggerfall files from API with the FileUsage.UseMemory option, FileProxy
class will now look for a .bytes file of the same name in your Unity Resources folder (e.g.
“arch3d.bsa.bytes”). This helps to create standalone builds (such as web builds) where the
Arena2 folder is not required, or only partial Arena2 data is needed.
Limited full validation checks in DaggerfallUnity to editor mode. This allows builds with
partial or no Arena2 data to launch correctly.
MeshReader, MaterialReader, and ContentLoader scripts are now set to
FileUsage.UseMemory to support Resources file support as above.
0.7.1

Initial release.