<br />
<b>Warning</b>:  Undefined array key "translationlc" in <b>/usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php</b> on line <b>237</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php:237) in <b>/usr/www/users/fabook/_diggets/doc/v2/inc/Action/Export.php</b> on line <b>104</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php:237) in <b>/usr/www/users/fabook/_diggets/doc/v2/inc/Action/Export.php</b> on line <b>104</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php:237) in <b>/usr/www/users/fabook/_diggets/doc/v2/inc/Action/Export.php</b> on line <b>104</b><br />
====== Using AssetsManager ======

{{:assets.jpg?nolink|}}

The AssetsManager is the core component in effective media management inside your Gorilla3D application. 
Models, textures, audio, dialogues and so on will be cached for faster access and reusage. 
You can build packages within the AssetsManager for modular media management. 
For example: you could build a package for the main character and reference to it in every scene package. 
Scene packages are extremly useful for compact and fast loading of all data in a scene.

===== Package =====

An assets package is the management unit to handle groups and their attached assets. Each asset can be a different type of media (model, texture, audio,...).
and is able to manage further sub-groups of assets.
This structure allows a complex and flexible asset structure for your project.

The assets manager allows two kinds of packages.

^Package Type ^Description^
|File-Based|The package data is loaded on-the-fly from file by a TFileStream. Do not modify position or data of that stream.|
|In-Memory|The package data is stored completely as TMemoryStream in memory. The data is compressed as zip-stream to reduce memory. Do not modify position or data of this stream.|

Packages are kept simple and transparent. File-based packages can be viewed easily by a typical ZIP-Viewer.
===== Groups =====
Each package provides a number of fixed group entries to organize media content.
Those groups are fixed to allow automatic load/save for specific media types.
For example: A model texture is getting loaded implicitly by loading the model, but the assets manager needs to know where to store.
By detecting the file extension he is able to organize the media file into the package.

Default group ids to access the specific group of each package are:

^ Constant  ^Value  ^ Extensions ^
| GORILLA_ASSETS_MODEL | 0         | *.obj, *.g3d, *.dae, *.stl, *.x3d, *.x3dvz, *.x3dz, *.fbx, *.gltf, *.babylon, *.ply, *.skp |
| GORILLA_ASSETS_TEXTURE | 1      | *.bmp, *.jpg, *.jpeg, *.dds, *.gif, *.png, *.tif, *.tiff, *.tga |
| GORILLA_ASSETS_AUDIO| 2          | *.aiff, *.asf, *.asx, *.dls, *.flac, *.fsb, *.it, *.m3u, *.midi, *.mod, *.mp2, *.mp3, *.ogg, *.pls, *.s3m, *.vag, *.wav, *.wax, *.wma, *.xm, *.xma (FMOD Support activated) |
| GORILLA_ASSETS_VIDEO| 3           | *.mp4, *.mpg and *.mpeg |
| GORILLA_ASSETS_MISC| 4              | *.txt, *.json, *.xml |
| GORILLA_ASSETS_DIALOGUE | 5  | *.dia, *.dlg|
| GORILLA_ASSETS_INVENTORY| 6 | *.iff |
| GORILLA_ASSETS_SKILLSYSTEM| 6 | *.ssf |
| GORILLA_ASSETS_SCRIPT| 7 | *.pas |
| GORILLA_ASSETS_PREFAB| 8 | *.prefab, *.prefabz |

===== Sub-Groups =====

Since 0.8.3 also assets can contain groups or so called sub-groups. 
This is getting important especially for TGorillaModelAsset which can contain textures, prefabs or scripts.
Because in elder assets manager versions it lead to name conflicts for textures, when models were loaded with equal texture names.

===== Assets =====
A media file is represented as extended TGorillaAsset instance inside in a specific group in an assets package.
Depending on the media type the asset holds the data.

==== TGorillaModelAsset ====

A TGorillaModelAsset holds model and animation data by the internal definition format TModelDef.
The asset converts all original model formats and writes them in G3D format to the zip-archive.

__**Caution:**__ The original file extension will be kept! Due to linked names inside of the structure, otherwise relinking model of load from package will fail.

The following example shows how to load and show a model from a file-based package.

<file pascal>
procedure TForm1.LoadMyModel();
var LGrp : TGorillaAssetsGroup;
    LAst : TGorillaModelAsset;
    LDef : TModelDef;
begin
  // load a file-based package
  FPackage := FPackage := FAssetsManager.LoadPackageFromFile('mypackage.zip');

  // get the model def from archive
  LGrp := FPackage.GetGroup(GORILLA_ASSETS_MODEL);
  LAst := LGrp.FindAssetByFilename('mymodel.dae') as TGorillaModelAsset;
  LDef := LAst.Model as TModelDef;

  // create a visual instance from model definition
  FModel := TGorillaModel.LoadNewModelFromDef(FViewport, LDef, []);
  FModel.Parent := FViewport;
  FModel.SetHitTestValue(false);
end;
</file>
==== TGorillaTextureAsset ====

TGorillaTextureAsset is a pseudo asset. It doesn't hold any data in memory.
When asset data is requested it will always load up the data from archive again.
The asset stores textures in PNG file format to the archive to preserve alpha channel.

<file pascal>
procedure TForm1.LoadImage();
var LGrp : TGorillaAssetsGroup;
    LAst : TGorillaTextureAsset;
    LBmp : TBitmap;
begin
  // load a file-based package
  FPackage := FPackage := FAssetsManager.LoadPackageFromFile('mypackage.zip');
 
  // get the model def from archive
  LGrp := FPackage.GetGroup(GORILLA_ASSETS_TEXTURE);
  LAst := LGrp.FindAssetByFilename('image1.png') as TGorillaTextureAsset;
  
  // this will request bitmap data from archive stream
  LBmp := LAst.Bitmap;
  try 
    // we then assign it to our image on the form
    Image1.Bitmap.Assign(LBmp);
  finally
    LBmp.free();
  end;
end;
</file>
==== TGorillaAudioAsset ====
Holds audio files in a TMemoryStream and writes those in original file format to zip-archive.

==== TGorillaVideoAsset ====
Holds video files in a TMemoryStream and writes those in original file format to zip-archive.

==== TGorillaMiscAsset ====
Used for unspecified file formats. Currently supported *.txt, *.json and *.xml.
Holds data in a TMemoryStream and writes those in original file format to zip-archive.

==== TGorillaDialogueAsset ====
Holds dialogue data in a TMemoryStream and writes those as *.dia file to zip-archive.

==== TGorillaInventoryAsset ====
Holds inventory configuration data in a TMemoryStream and writes those as *.iff file to zip-archive.

==== TGorillaSkillsAsset ====
Holds skill system configuration data in a TMemoryStream and writes those as *.ssf file to zip-archive.

==== TGorillaScriptAsset ====
Holds a script file in a TMemoryStream and writes those as *.pas file to zip-archive.

==== TGorillaPrefabAsset ====
Holds a prefab file in a TMemoryStream and writes those as *.prefab or *.prefabz file to zip-archive.

===== DesignTime =====
You can find the TGorillaAssetsManager component in the toolbar. Simply drag and drop onto your form.

In the next step we need to create a new package in "Packages" property by the Delphi collection editor.

Setting the filename of a package will initiate the IDE to load the package into memory.

**WARNING**: relative paths are not recommended, because at designtime you are in the working directory of BDS.exe.

To use relative paths on packages, we provide a set of preset values:

^Placeholder^Description^
|'{HOME}'|Calling System.IOUtils.TPath.GetHomePath()|
|'{ASSETS}'|Calling  System.IOUtils.TPath.GetHomePath() + "\assets\"|
|'{DOCS}'|Calling System.IOUtils.TPath.GetDocumentsPath()|
|'{LIB}'|Calling System.IOUtils.TPath.GetLibraryPath()|
|'{PUBLIC}'|Calling System.IOUtils.TPath.GetPublicPath()|
|'{DOWNLOADS}'|Calling System.IOUtils.TPath.GetDownloadsPath()|
|'{SHARED_DOCS}'|Calling System.IOUtils.TPath.GetSharedDocumentsPath()|
|'{SHARED_DOWNLOADS}'|Calling System.IOUtils.TPath.GetSharedDownloadsPath()|

**Notice**: Called internal functions of TPath are platform dependent.
Please take a look at Embarcadero documentation for further information, f.e. [[https://docwiki.embarcadero.com/Libraries/Sydney/en/System.IOUtils.TPath.GetHomePath]]


Set the "Filename" property of a pckage to the following path, to create/load a package on Windows at:

//"C:\Documents and Settings\<username>\Application Data\mypackage.zip"//

<file pascal>
TGorillaAssetsPackage.Filename := '{HOME}mypackage.zip';
</file>

===== Example =====

==== Creating package at runtime ====

Alternatively you can create the assets manager and packages at runtime.

<file pascal Form1.pas>
var 
  FAssetsManager : TGorillaAssetsManager;
  FPackage : TGorillaAssetsPackage;
  
procedure TForm1.CreatePackage();
begin
  FAssetsManager := TGorillaAssetsManager.Create(Self);
  FPackage := FAssetsManager.AddEmptyPackage(GORILLA_PACKAGE_DEFAULT);
end;
</file>

==== Loading package from file ====

You can easily setup packages by the Gorilla3D assets manager tool.
There you can also save packages to file, which can be loaded at runtime in your program.

<file pascal Form1.pas>
procedure TForm1.LoadPackage(const AFilename : String);
begin
  FAssetsManager := TGorillaAssetsManager.Create(Self);
  FPackage := FAssetsManager.LoadPackageFromFile(AFilename);
end;
</file>

==== Storing your assets package at runtime ====

Of course you are allowed to store the assets package you've setup.
Easily use the provided SaveToFile method of each package instance.

//Notice: In case your are working with a file-based package and the destination location is the same, nothing will be stored.
If the destination differs from currently loaded package, it will create a copy of the file package.//

//Notice: In case you are working with an in-memory package, it will be stored to file, but it stays in memory for further work.
If you want to load the stored in-memory package, you have to use the TGorillaAssetsManager.LoadPackageFromFile() method.//

<file pascal Form1.pas>
procedure TForm1.SavePackage(const AFilename : String);
begin
  FPackage.SaveToFile(AFilename);
end;
</file>

==== Finding an asset inside of a package ====

1) Each assets has an unique id (GUID) when added to the package by which we can find it exactly.

<file pascal Form1.pas>
  // finding an asset in a specific group by its unique id
  LAssetId := '{18E01973-D452-4596-A1A1-C51F09763954}';
  FPackage.GetAssetFromId(GORILLA_ASSETS_TEXTURE, LAssetId);
</file>

2) Get asset by its filename

**Caution: This method will automatically import the asset from supplied file, if it can not be found.**

<file pascal Form1.pas>
  // finding an asset in a specific group by its filename
  LAssetFile := 'texture0.png';
  FPackage.GetAssetFromFile(GORILLA_ASSETS_TEXTURE, LAssetFile);
</file>

3) Get asset by its filename and stream

**Caution: This method will automatically import the asset from supplied stream, if it can not be found.**

<file pascal Form1.pas>
  // finding an asset in a specific group by its filename
  LAssetFile := 'texture0.png';
  FPackage.GetAssetFromStream(GORILLA_ASSETS_TEXTURE, LAssetFile, AStream);
</file>

Next step: [[billboard|Billboard]]