General Overview
From Blender2crystal
This document describes the generics you need to know to be able to understand blender2crystal in a high level way.
Contents |
[edit] Interface
Blender2crystal uses mainly an overlay interface that can be loaded over the blender 3d windows, also features a regular blender script interface with some additional functionality.
It is recommended to use the overlay interface to set all properties, even if there are other ways to do it (adding properties manually, or editing xml metadata files).
There are some documents in this manual that explain all the little details about the interface:
- Overlay Interface Explains the object related properties and tabs.
- Cel Overlay Interface Explains the entity tabs in detail.
[edit] Object Types
Each of the object types in blender corresponds to some crystalspace type. For example a blender Lamp will result in a crystalspace light.
In some cases the type for an object can be changed, specially with blender Mesh objects, that can correspond to a variety of crystalspace types. Depending on the real time treatment we want them to receive it is necessary to set the appropiate type (like terrain, particles, thing, genmesh).
You can check and change the type of an object at the object info tab (
).
There is more information about this at Object Type Reference
[edit] Sectors / Regions / Zones
CS maps are usually divided into multiple sectors. This is emulated by blenders scenes. Each Scene becomes a sector of the same name, and they can be connected using special objects called portals.
Check the Portal tutorial for more information on starting with scenes and portals.
[edit] CEL region export mode
It is possible to use an special export mode (select cel, then regions in main exporter window) in which sectors will be exported to separate files. Also in this mode sectors can be associated to regions and zones to get autoloading/unloading of sectors using cel zonemanager.
Each sector must be assigned to one region by using the region property in sectorsettings. By default sectors get exported to a region called "main", so it is not necessary to set this for the scenes in your first region.
Each region must then be assigned to one or more zones. This is done somehow indirectly with the exporter. You just set your sectors to the zones you want them to be in, and it will figure out what regions to put in each zone. The zones for a sector are set with the zones property in sectorsettings as a list of strings separated by commas.
Keep in mind when using zones and sectors that the zones must overlap that is, you are always in one zone or more, and unloaded zones won't even be seen through portals.
Each zone should consist at least of a sector and all sectors visible from this. New zones will be loaded once you get into them (by coming into a region that is both in the zone you came from and in the zone you are now getting into).
[edit] Factories and Objects
In CrystalSpace as in blender there is a clear distinction between an object and the mesh data it references (the factory). Thus, several objects can share a factory and save space and processing time.
The correspondency between blender "Mesh Data Objects" (named after the code ME as in ME:cube.001) and CrystalSpace "Factories" is not straightforward, as different functionalities are present in each system, and also in crystal there are different mesh types not present in blender.
The main concern here, is to clearly distinguish in blender between ME (mesh data) and OB (reference object). The object is the individual we are considering, and the mesh data is the data possibly shared between objects.
When exporting the ME object name will be assigned to the CrystalSpace factory, and the OB object name to the meshobject. Both names can be set up in blender from the edit tab in the buttons window (and also in some other places).
Data sharing is easiest achieved in blender by using the combination ALT D to link duplicate the object. Then when modifying one object the other will also be modified in blender. Note factory instances with different object size wont share data in crystalspace.
Currently factories are generated for terrain, thing, genmesh, spr3d, particles and cal3d types.
[edit] Renderloops
The renderloop represents the kind of lighting we want for a sector. This is a very important concept to use crystalspace materials successfully, as each of them serves for a particular render loop. For example there are renderloops for terrain sectors (terrain, terrainf), for fixed lighting (standard), dynamic lighting (diffuse) and different kind of shadows (shadowed, shadowed2, shadowmap...).
The renderloop can be set in a worldwide manner at the world tab (
), or per sector at the Sector tab (
).
- ambient: ambient term lighting. Just renders the geometry with the ambient term, no lights.
- diffuse: dynamic lighting. An ambient pass and lights pass.
- fattest: is an experimental renderloop that is supposed to auto adjust to all conditions.
- shadowed: dynamic lighting with shadows. The shadows are sharp edged and its heavier on the processor so there will be a fps drop.
- shadowed2: dynamic lighting with shadows. It is faster than shadowed renderloop but it will only do shadows for closed objects.
- shadowmap: dynamic lighting with shadows. Does shadows using projected textures. (experimental)
- standard: static lighting with precalcalculated shadows.
- terrain: dynamic lighting for worlds with terrain.
- terrainfixed: static lighting with precalcalculated shadows for worlds with terrain.
[edit] Materials
Materials are handled in a very different way in blender than in crystalspace, as the scope of each infrastructure is very different. Because of this, a special material tab (
) exists in blender2crystal to set crystalspace related material properties.
You should check the First steps with blender2crystal tutorial for some info on starting with materials.
[edit] Lights
Lights are exported from blender using their specified colour and distance, also some of the light types are respected.
[edit] Light types available
Spot lamps will be exported as CrystalSpace spotlights. (useful for projection bumpmaps)
Sun lamps will be exported as a special light with influenceradius: 10000000, attenuation:realistic and radius: 0. This is generally used alongside ScatterSky material set on some sky object with skysize property set.
All other lamp types will be exported as normal point light sources.
[edit] Parenting
You can parent objects in blender and they will be exported as similar object hierachies in crystalspace.
[edit] Sequences
Blender IPO animations can be exported into crystalspace. For the moment the IPOs supported are translation and rotation for thing, spr2d, particles and genmesh, translation, rotation and RGB for lights.
Note this section does not apply to armature animation.
One of the Blender curve extend modes is supported: Cycle. Unless set the animation will only run once (the same as constant extend mode in blender). The same setting will be used for all the curves in an IPO, totally independent extend modes for curves will be implemented at some (remote) future time.
Keep in mind that animation support is currently quite limited, and not all complicated cases will work. Try to follow the following rules:
- Make keys in the same frames for all ipos, ie, having ipo keys in different places in each ipo is not really supported at the moment.
- Dont mix location and rotation ipos, ie having LocRot ipos wont give the expected results.
Sequences are triggered by default when the sector they are in comes into view. It is also possible to set some other trigger types by using the seq_trigger property, at the object properties tab (
) to set different kind of triggers for the sequence, or wether it should be initially active.
[edit] Physics
Blender2crystal supports assigning physics properties to objects for simulating through crystalspace Dynamics plugins or CEL mechanic pcproperties. This allows for simulating physical behaviour realistically.
There is a more detailed reference about b2cs physics support at Physics Reference.
[edit] Entities and advanced interaction
Blender2crystal has extensive support for CEL (Crystal Entity Layer), a set of plugins with increased support for game making and game scripting, that simplifies game creation and provides a great set of game classes to breathe life to your blender objects.
You can read further about CEL support in the following documents:
[edit] Exporting libraries
Apart from exporting worlds to run directly sometimes it is needed for a game to create library files. To do this just select the library toggable at the export (
) tab. Then the exported files will use the <library> tag instead of the <world> tag and so you cant run them directly with walktest any more.
There is an special inlinefactories property that makes the exporter inline the factory files inside the main library file, this allows for all data to reside in just one file, and can be desired in some situations. In general you shouldn't need this.
