From C4 Engine Wiki

Under Construction This article is still under construction and may contain sections that are incomplete.

Introduction

This article shows the steps for importing either an animated or static textured model into the C4 Engine using the World Editor, and then shows how to view the imported model in the Model Viewer.

We assume a certain degree of familiarity with the World Editor, and so we do not go into any detail about how to use the model in a game once it is imported.

We import a sample model contained in a single COLLADA file, with animations contained in a separate folder, where each animation is contained in its own file with the extension .dae.

We initially extract the archive to a temporary location, look at the contents, and build a folder structure that C4 can work with. We then take a look at the COLLADA file's image locations, and modify the files paths to show the best practice when importing texture images into C4 that are part of a model.

Importing a static or animated model into C4 should be a simple process, once resources are placed in the correct locations. We'll show how you can make a small change to the image locations referenced by your project to make that process work. But sometimes the best laid plans can go awry, so we'll also show some alternate workflows when textures are not imported, or when the model is exported at a position that is too low to view in the Model Viewer.

The workflow for static and animated models is almost the same. A static model imported into C4 is generally referred to as a geometry, and an animated model is referred to as a model. The difference is that the C4 model needs a controller to be written and applied, in order for the animations to be functional in the engine. For models to be visible in the Models listbox in the World Editor's Models page, the model's controller needs to be registered with the Game, which is beyond the scope of this article.

Folder Structure

For this tutorial we will be using the Alien creature that has been exported from Max described in this article, the files are located here. Extract the archive to a temporary location, this can be anywhere but not in the C4 folder yet. We need to view the contents and only copy over the files and folder we actually need.

As mentioned earlier, it is very important that the resources (the model, the animations and the textures) are copied to a location and folder structure that C4 can read correctly. When a text file or texture is imported into C4, it can only be imported from the Import folder and will be copied (when converted to the respective binary format that the engine requires) over to the same sub location in the /Data/ folder. Though there is one caveat that must be adhered to, files may not exist in the actual root /Import/ folder itself (And also the /Data/ folder), they must be held in a sub folder underneath Import. An example of the import process on a stringtable for example would involve a file resident in /Import/MyGame/strings.txt being copied to /Data/MyGame/strings.str, the file's parent folder is automatically created in the Data folder when the conversion takes place.

With this on mind, the first step is to create a directory structure in the /Import/ folder for the models, textures and animations so that they can be read by the engine converted and copied to the Data folder.

In the C4 root folder you will find the /Import/ folder, create a new folder under this called MyGame (or the name of you project, but for this article we will use MyGame), so that it looks like the following image.

In the MyGame folder, create a new folder called models and another called textures.

Let's go back to the extracted archive and view the contents as we need to identify the files and folders that will be part of this tutorial.

Copy the files in the archive's Collada folder to the /Import/MyGame/models folder so that the structure now looks like

Finally copy the files from the archive's Textures folder to the /Import/MyGame/textures folder so that the structure looks like

We now have the import folder set up correctly, so you can go ahead and close the extracted archive folder as it will not be required any further.

Importing the COLLADA Model

Before we import the Alien.dae COLLADA file, we need to make sure that the file is set up to correctly reference the textures used by the model - that is, the C4 import process needs to be able to locate the textures during the import process.

It's worth discussing at this point about adhering to a structure that works for your project. Obviously it would be quite difficult to work entirely within the C4 folder structure when saving models and textures. But more advantageous to have a folder structure that enables the models and their respective animations and textures to be copied over without any manual configuration at all.

The importer is able to import the model as well as any dependent textures automatically, this is achieved by looking for the image locations described in the COLLADA file. For example the following structure in a model's .dae file describes the image's physical location of the Diffuse image.

<library_images>
    <image id="Model_Diffuse.tga" name="Model_Diffuse.tga">
        <init_from>C:/MyGame/textures/Model_Diffuse.tga</init_from>
    </image>
</library_images>

Each image has an id and a name, in the above case it happens to be the name of the image and the <init_from> tag specifies the location of the image file. The importer looks for the string /Import/ in the file path and if it finds it, strips off any text before /Import/ and also the text /Import/ itself as it is assumed that the Import folder is being used for the location. If /Import / is nowhere in the path, the importer just uses Model_Diffuse.tga as the path as in the above example. As there is not a specific path for the texture resource, it cannot be automatically imported. Once the model has been imported material is created with the texture names entered but without a path to the texture, the Texture map (primary) in the Material Manager would read Model_Diffuse (And the missing texture used until the textures are correctly imported and the correct path is entered)

<library_images>
    <image id="Model_Diffuse.tga" name="Model_Diffuse.tga">
        <init_from>C:/Import/MyGame/textures/Model_Diffuse.tga</init_from>
    </image>
</library_images>

In the above example, the physical location is almost the same as the previous example apart from where we have now added the text /Import/ into the path. The import process will now assume that the texture resource has the path MyGame/textures/Model_Diffuse.tga inside the C4 /Import/ folder. If the textures are located in this location, they are automatically imported and placed into a folder MyGame/textures/ in the /Data/ folder, Model_Diffuse.tga becomes Model_Diffuse.tex. You are probably thinking that the Texture map (Primary) would be displayed as MyGame/textures/Model_Diffuse, unfortunately not. The resources in the C4 Engine are always described and accessed without the sub-folder underneath the /Data/ folder. So the texture resource would be entered as textures/Model_Diffuse.

A bit of history about how the C4 Engine handles resources in the /Data/ folder when accessing said resource through any part of the user interface. When referring to textures, models, animation in fact any resource within the /Data/ folder the engine always strips off the /Data/ folder (and if you remember that we mentioned previously all resources must be held in a sub-folder of /Data/) and the next folder underneath /Data/. So a texture held in /Data/MyGame/textures/MyTexture.tex would always be referred to as textures/MyTexture.tex. This also presents an issue in that two textures with the same name in a similar folder structure, but only having a different Data sub-folder would be interpreted as the same logical name. In this instance the first texture in the search is the one referenced and this will depend on if the folder iteration is working forward or backward to find the image. Finally if you have a resource with the same name and location packed in a .pak file, this will take precedence over a physical file location irrespective which way the search is performed, .pak files are always searched first. Good advice is to try and use unique names for you resources.

It is therefore a good idea to have /Import/ in your project structure when the structure contains resources that will at some point be imported into C4.

Back to the Alien.DAE file that we are importing, if you open the file in a text editor and view the contents, you will see that we will need to manually update the image locations.

<library_images>
    <image id="Alien_Diffuse.tga" name="Alien_Diffuse.tga">
        <init_from>file:///C:/Documents%20and%20Settings/Frank/Desktop/3drt.com-free-monster-animated-character/C4/Alien_Diffuse.tga</init_from>
    </image>
    <image id="Alien_Gloss.tga" name="Alien_Gloss.tga">
        <init_from>file:///C:/Documents%20and%20Settings/Frank/Desktop/3drt.com-free-monster-animated-character/C4/Alien_Gloss.tga</init_from>
    </image>
    <image id="Alien_Bump.tga" name="Alien_Bump.tga">
        <init_from>file:///C:/Documents%20and%20Settings/Frank/Desktop/3drt.com-free-monster-animated-character/C4/Alien_Bump.tga</init_from>
    </image>
</library_images>

Change the paths to the values below to reflect the actual locations within the /Import/ folder.

<library_images>
    <image id="Alien_Diffuse.tga" name="Alien_Diffuse.tga">
        <init_from>/Import/MyGame/textures/Alien/Alien_Diffuse.tga</init_from>
    </image>
    <image id="Alien_Gloss.tga" name="Alien_Gloss.tga">
        <init_from>/Import/MyGame/textures/Alien/Alien_Gloss.tga</init_from>
    </image>
    <image id="Alien_Bump.tga" name="Alien_Bump.tga">
        <init_from>/Import/MyGame/textures/Alien/Alien_Bump.tga</init_from>
    </image>
</library_images>

Finally it's time to import the Alien model. Create a new blank world and from the World menu or the model can be imported directly into an existing world if is does not have any animations, but for this article we will be using animations, so, select Import Scene.

When the Import Scene dialog is displayed it automatically defaults to the root /Import/ folder, navigate to the model's location as shown by the path in the image below, and click OK

A second dialog is displayed asking if you would like it to attempt to import the texture maps. This is asking if it should also look for the textures described in the COLLADA file and import them. If they cannot be found, the texture name will be displayed in the Material Manager (mentioned earlier). Check the check box and click OK

The model has now been imported into the current world, if the textures are found they are imported into their respective locations in the /Data/ folder and the model is displayed fully textured, as seen in the image below. If the textures we not imported then have a look at the this section

What could possibly go wrong?

At this point, the orange lines that represent the skeleton of your model may not line up with the gray lines that represent the triangle mesh of your model. If this is the case, then something is wrong in the pipeline used to create the DAE file, and you need to fix it there -- you cannot fix this in C4 itself.

Examples of problems that could cause this include:

• Using an old version of the Collada exporter. The Autodesk Max and Maya exporters are especially known to be bad.
• Not resetting the transform of your skeleton bones before you bind them to the mesh skin modifier.
• Not resetting the transform of your mesh (google for "the box trick") before binding bones to it.

(These are mostly from 3ds Max; if you know how this happens when using other tools, please add here)

Exporting the C4 Model

The static model import process stops before exporting the model file, this world can be saved and used as a referenced world within existing world files (great for instances of the same geometry) and you will not need to complete the next steps. Sometimes though you might just want to import geometry but not have a suitable world to import it into and quickly see what it looks like fully lit, and it is a lot easier to quickly import and view in the model viewer. Bear in mind though that you cannot do anything with the model file if you do not write a controller for it.

Before we export the model we need to create a location for it in the /Data/ folder if you open the data folder, you will see that a new folder called MyGame has been created, expand MyGame and notice another folder textures - this contains the textures that have been imported from the previous steps of the import process. Create a new folder underneath MyGame called models and a new folder called Alien underneath the models folder. The folder structure should now look like the image below.

Time to export the current world file as a model. From the World menu, select 'Save to Model Resource...'

A dialog is displayed, navigate to the MyGame/models/Alien folder and type Alien into the text box at the bottom of the dialog and click OK. If you browse to this folder, you will see a new file has been created called Alien.mdl - the C4 Engine's proprietary model format.

To view this model in the model view, from the Tools menu, select Open Model...

Navigate to the folder that you have just saved the model to, MyGame/models/Alien and select Alien.mdl, click OK.

The imported model is now displayed in the Model Viewer

Importing the COLLADA Animations

As it stands now, the model has been imported and displayed correctly in the model viewer, so we can start to import animations. The animations must reside in the same folder as the model, luckily we have saved the model in the /Data/MyGame/models/Alien folder, and the animations are currently located in the /Import/MyGame/models/Alien folder, so when they are imported, they will end up in the correct folder (Remember, when importing from the /Import/ folder, the files are imported into a similar location in the /Data/ folder).

From the main Model Viewer window, click on the Import button on the left. The Import Animation dialog is displayed, navigate to the MyGame/models/Alien folder and select the first animation file Alien_Attack1.dae. Click OK

The imported animation is now displayed in the Animation list box.

Click Import again and import the rest of the animations and they are displayed in the list box. If you browse to the physical /Data/MyGame/models/Alien/ folder, you can see that the animation files have been imported with a .anm file extension.

The final animations can be viewed by selecting the animationa and clicking play, here is a video of the end result.

Problems

Manually Importing the Textures

Aligning the Model