• General Questions
• Character Modeling and Exporting
• Programming
• Compiling and Building

What is Cal3D?

Cal3D is a skeletal based 3D character animation library written in C++ in a way that is both platform-independent and graphics API-independent. It was originally designed to be used in a 3D client for Worldforge, but evolved into a stand-alone product which can be used in many different kinds of projects.

Cal3D's essentials can be boiled down to 2 parts: the C++ library and the exporter. The exporter is what you would use to take your characters (built in a 3D modeling package) and create the Cal3D-format files that the library knows how to load. The exporters are actually plug-ins for 3D modeling packages. This allows 3D artists to use the modeling tools that they're already comfortable with.

The C++ library is what you would actually use in your application, whether it's a game or a VR application. The library provides methods to load your exported files, build characters, run animations, and access the data necessary to render them with 3D graphics.

Primarily, Cal3D is useful for putting animated 3D characters into your interactive graphical applications.

The exporters provide a bridge for users to take their characters created in a 3D modeling package to their own applications, where they will have control over the characters' actions.

Cal3D can perform animation blending. This means that you can execute multiple animations at the same time and Cal3D will blend them together smoothly. This effect is best demonstrated in the Cally Demo, where the walking, running, and strutting animations can be blended together in any ratio to get a wide variety of movement characteristics.

Cal3D also provides an automatic level-of-detail control, which allows you to scale back the number of polygons that make up your character at runtime. This can be a good performance boost when your character is farther away and the lower detail isn't noticable to the viewer.

With a little work, you can fully manipulate the individual parts of your characters. This is useful when you want to create truly dynamic motion at runtime without the aid of predefined animations. For instance, if you wanted your character's head to turn as a car goes past him, you could control the head's rotation directly to keep facing the moving car.

Cal3D doesn't do graphics. The users are responsible for making a bridge between Cal3D and whatever graphics API they want to use. This includes things like loading textures, handling materials, and rendering the models to the screen.

The source code for the Cal3D miniviewers is a good place to start, as it provides a full implementation for both OpenGL and Direct 3D graphics APIs that you can adapt for your own purposes.

Cal3D can't help you make animated models. Making a decent character will require the use of a modeling package like 3D Studio MAX, using the tools that it provides. Making a really excellent character requires a talented artist.

Cal3D doesn't load configuration files. This is a responsibility left on the users' shoulders for another degree of flexibility. And again, an example of how to do this is contained in the miniviewer examples.

Yes, Cal3D is quite stable and efficient enough for a lot of games. Several published games have used Cal3D successfully.

This is a fairly subjective question, as Cal3D's speed is highly dependent on things not controlled by Cal3D. Developer choices like which graphics API to use can impact the speed, as well as using GPU programming languages. The complexity of the models plays a big role in this as well - not only the polygon count, but also the complexity of the underlying skeletal structure.

Cal3D is certainly capable of operating fast enough for many practical applications and games. While we don't have an official benchmark, tests have been done in the past involving 20-30 characters at a time and reasonable framerates were achieved.

The short answer is yes. Cal3D is released under the Lesser GNU Public License (LGPL), which allows you to link in the Cal3D library for your commercial game or simulator or whatever.

The catch, however, is that if you make changes to Cal3D and use them, you are obligated to release the source code under the same license.

Cal3D is written to be cross-platform. It works on Windows, SGI Irix, various flavors of Linux, Mac OS X, etc.

Basically all you need is a decent C++ compiler with standard template library support. If you want to use the build system, you either need Visual Studio on Windows, or GNU's autotools on *nix systems.

Cal3D is designed to be independent of any graphics API such as OpenGL or DirectX. While this makes Cal3D more flexible, it does put a little more work on the users.

We have several examples of our miniviewer application that can show you how to use Cal3D with various graphics APIs such as OpenGL, Direct 3D, or even shader languages.

Keep in mind that these examples only show one way how to do it; you are free to develop your own methods and techniques specific to your application.

Worldforge - http://www.worldforge.org - This is an open source project aimed at developing tools for massive-multiplayer online games. Cal3D was originally a part of Worldforge, but became a standalone tool.

A Tale in the Desert - http://www.atitd.com - ATITD is a very unique massive-multiplayer online roleplaying game where strategy and management take precedence over traditional combat. eGenesis used a derivative of Cal3D that they developed, which is also available on their "download" page.

Desert Rats - http://www.valusoft.com/products/desertrats.html - A WW2 action game where you fight the Nazis in northern Africa from a heavily armed jeep.

Neverending ODC - http://ne-odc.sourceforge.net - Tools to design and edit massive 3D fantasy worlds.

The Nebula Device - http://nebuladevice.sourceforge.net/cgi-bin/twiki/view/Nebula/NCal3DPackage

• An open source 3D game/visualization engine designed to be highly scriptable. Their package, nCal3D, allows Nebula users to easily integrate Cal3D into their own applications.

If you know of anyone else using Cal3D, let us know! Can I just load my 3D Studio MAX files directly into Cal3D?

No. You have to export your character to Cal3D-format files. There are many different things besides just animated figures that can be included in a 3DS file, and to make the Cal3D library sort these things out automagically would be an incredibly difficult task.

Plus, you can only have a single animation stored in a 3DS file and characters will typically have a variety of animations to choose from.

How do I make new characters?

This is a job for an artist. Generally, one would create a mesh model of a character, create a skeletal system for it, animate it, and then export all of the pieces using the Cal3D exporters. (Skeleton, meshes, materials, and animations)

We currently have exporters for 3D Studio MAX and Milkshape 3D.

3D Studio MAX - http://www.discreet.com/products/3dsmax
Milkshape 3D - http://www.swissquake.ch/chumbalum-soft

1. First, export the skeleton.

The remaining steps can be performed in any order:

2. Export the mesh or meshes.

3. Export the materials.

4. Export the animations.

First, you need to select the skeleton (and ONLY the skeleton). Then go to File->Export and select the Cal3D Skeleton exporter. You will be asked to choose from a list of bones. It's possible for each bone to appear more than once in the list, so make sure you only select each bone ONCE.

Before exporting your mesh(es), make sure you've already exported your skeleton. And if your character has more than one mesh, you'll need to export each mesh separately. Be sure to select just one mesh at a time.

Once you're got your mesh selected, go to File->Export and choose the Cal3D Mesh exporter. You will be asked to locate a skeleton file. Pick the skeleton file (.csf) that was exported based on the same character as your mesh.

There are some tricks to this. The main thing is that the materials have to be named properly. Each material name that the character uses needs to end with a number enclosed in brackets, starting with 0 and going up.

For instance, if a character has materials for skin, shirt, face, and hat, them the materials should be named like this:

skin [0]
shirt [1]
face [2]
hat [3]

Before exporting your animations, make sure you've already exported your skeleton.

Once you've got your character animated, take your character out of Figure Mode, go to File->Export and choose the Cal3D Animation exporter. You'll have the option of a number of frames per second and the selection of individual keyframes to use in the animation.

Like mesh exporting, you'll be asked to find the Cal3D skeleton file (.csf) that the character is based on.

Usually this is a result of having things selected that you shouldn't have. There can also be crashes caused by mis-named materials or failing to collapse the modifer stack before exporting.

Jiba at OOMadness has released a GPL'd Python script that allows Blender users to export Cal3D objects. Find it here: http://oomadness.tuxfamily.org/en/blender2cal3d/index.html

There have been rumors of people working on a Cal3D exporter for Maya, but it has not been released yet.

To do this, you need to collapse the bone trajectories. Select all of the model's bones. Open the Motion panel, and then the Trajectories tab. Click the Collapse button.

Previous to version 0.9, the textures for the Paladin sample model were contained in a RAW image file format. The current developers are not sure where they originated from, but they have (as of version 0.9) been converted to TGA files.

These old RAW files are no longer supported or necessary.

Are there Python bindings for Cal3D?

Yes. The Py3D project has Python bindings for Cal3D. You can get them at the Py3D website:

http://www.py3d.org/pycal3d

Cal3D characters exported from a modeling package such as 3DSMax or Milkshape will be in the same coordinate system as the package. For instance, a model exported from MAX and loaded for use in an OpenGL application will require a -90 degree rotation about the X-axis to be converted to the OpenGL coordinate system.

It should also be noted that Cal3D's math classes assume a left-handed rotation system. Right-handed systems are much more common, so this is not a minor detail. Think of it like this: take your right hand and point your thumb straight up while curling your fingers a bit - kind of like you're holding a coffee mug.

Your thumb is the vector axis of rotation. If you have a positive-value rotation, you will be rotating counter-clockwise about your thumb's axis. If you have a negative-value rotation, you'll be rotating clockwise.

Now do the same thing, but with your left hand. Note that your fingers now curl around clockwise. So with positive rotation values in a left-handed system, you get a clockwise rotation. This is the opposite of the right- handed system.

In practical applications, there may be many different instances of a single type of character. For instance, your game might pit the hero against an army of robots. Some of these robots might look identical, and can then share data with each other rather than having a separate copy of it for each robot.

The core objects (skeleton, meshes, materials, bones, etc.) contain the data that will not change at runtime and can therefore be shared between multiple independent characters. The non-core classes contain data about things that frequently change, such as the animation state and mesh data. This allows the instances to share data and still be able to be animated independent of one another.

There are a few ways to get your Cal3D characters working within an application that uses a scene graph.

The easiest way is to simply draw your characters using OpenGL after you've drawn your scene graph. This can be inefficient, however, because you lose the culling features that the scenegraph provides. Plus you need to be very careful about the OpenGL state, which is changed by the scene graph constantly.

Most major scene graphs support draw callback functions. Using these, you can basically attach a Cal3D character to a node inside the scene graph and the character can be drawn (using your OpenGL commands) automatically as the scene graph is traversed. This approach requires a little more work, and will be different depending on the specific scene graph you're using.

If you're interested in using OpenSceneGraph, there's a Sourceforge project called osgCal that provides an adapter to put Cal3D models into OSG applications. Find it here:

http://osgcal.sourceforge.net

What's with these missing DLL errors when I run the Cally demo?

You may have gotten a message pop-up saying that the MSVCP70.dll file could not be found when trying to run the Cally demo.

The Windows binaries for the 0.9 version of Cal3d (and the demo) were compiled with Visual Studio .NET (VC70). Non-XP versions of Windows may not have the right C/C++ runtime DLLs that are needed.

These are available as part of Microsoft's .NET Framework package, which can be downloaded from here:

http://msdn.microsoft.com/netframework/downloads/howtoget.aspx

In order to compile the 3D Studio MAX exporter, you need the 3DSMax SDK (Software Development Kit) and the Character Studio SDK. When you install MAX and/or Character Studio, there will be an option to also install the SDKs.

For the Milkshape exporter, you need to get the Milkshape SDK, which is available separately from their website:

http://www.swissquake.ch/chumbalum-soft/ms3d/download.html

You need to have the Character Studio SDK installed, which contains these header files.

Cal3D's exporters are known to work with 3DSMax 3, 4, and 5. This includes Character Studio 4 as well.

Generated at Sun Oct 12 18:38:51 2003 by The Cal3D Team with 1.2.14 © 1997-2001 Dimitri van Heesch