Plugin Blender-Nel : Cahier des charges

D'autres approches ont été explorées puis abandonnées :

• Export/Import NEL via Collada
• remplacer une partie de Nel par Ogre, ce qui change complètement la façon dont la pipeline pourra fonctionner.</WRAP>

Document de travail pour le développement d'une extension destinée à aider la création de modèles 3D NEL dans Blender.

Philosophie

Le succès d'un projet libre se mesure dans la capacité de la communauté à se l'approprier et à le faire vivre. Un énorme travail a été effectué par l'équipe Ryzom Core pour fournir une chaîne de production libre nécessaire à la genèse d'un monde. Il manque encore à cet ensemble un élément essentiel : un outil libre pour la modélisation 3D des objets de l'univers. Ce document est une proposition qui vise à combler ce manque.

L'application propriétaire 3D Studio Max est l'outil utilisé en amont pour la création de l'ensemble des éléments 3d du moteur de jeu (terrain, bâtiment, personnage et animation, micro-végétation, billboard, etc…). Une extension dédiée https://ryzomcore.atlassian.net/wiki/display/RC/Installing+the+Max+Plugins permet de :

• Configurer l'environnement de travail 3D Studio Max afin d'intégrer la base des assets du moteur et préparer l'espace de travail pour les différentes tâches
• Exporter des modèles 3d vers les formats natifs de la bibliothèque NEL.
• Intégrer 3D Studio Max à la chaîne de production via l'enregistrement de l'application comme un service COM sous Windows.

3D Studio Max est un outil de qualité, reconnu par les professionnels et répondant parfaitement à la problématique de modélisation 3D. Cependant dans le cadre d'un projet libre, il est source de contraintes fortes :

• Outil propriétaire à la licence onéreuse : ce double aspect constitue un frein important pour une communauté libre et limite donc la base d'artistes pouvant enrichir cet environnement.
• Format propriétaire et fermé des fichiers .max qui remet en cause la pérennité des modèles créés avec cet outil mais bloque aussi la création d'outils annexes pouvant manipuler nativement ces modèles.
• Outil ne fonctionnant que sous Windows.

Il existe dans le monde libre un outil capable de rivaliser sans rougir avec des logiciels commerciaux comme 3D Studio Max. Il s'agit de la suite d’outils de modélisation 3D et de rendu dénommée Blender.

Objectif

L'application Blender s'articule autours du langage de scripting Python. Les dernières versions de l'application utilisent le langage python pour construire l'interface utilisateur au dessus du noyau de la suite. L'API python permet d'accéder à toutes les fonctions internes de Blender depuis ce langage. Ainsi les scripts écrits dans ce langage étendent les fonctionnalités de Blender sans avoir à recompiler/“linker” le code source du programme en binaire.

Ce projet consiste donc à développer une extension Blender en python pour :

1. Exporter les scènes 3D construites dans Blender vers les formats natifs NEL afin d'être utilisables par le moteur RyzomCore.
2. Faciliter la constructions de modèles 3D destinés à RyzomCore en pré-paramétrant l'environnement de travail Blender et/ou en étendant les interfaces de manipulation de scènes 3D pour se concentrer sur ce qui est spécifique aux objets NEL.
3. Intégrer Blender à la chaîne de production des data du jeu (scripts en ligne de commande de génération des data à partir des données sources)

État des lieux

Le plugin Nel3DSMax est composé d'une librairie écrite en C++, et de scripts utilisant le langage maxscript spécifique à 3D Studio Max. La librairie C++ s'appuie sur le SDK1 de 3D Studio Max pour accéder aux structures de données internes de l'application et reconstruite à partir de celles-ci les objets 3D NEL avant de les sérialiser dans les différents formats propres à NEL. Les scripts servent essentiellement à initialiser l'environnement et fournissent des outils de manipulation des assets graphiques.

Contenu des dossiers du plugin Nel3DSMax (dans code/nel/tools/3d/plugin_max) : *

• macroscripts : il contient 3 script au format .mcr ( les scripts au format .mcr permettent d'associer une commande (script?) à un élément de l'interface de l'application )
• nel_3dsmax_shared : code d'initialisation de la librairie (enregistrement de la DLL, initialisation d'un contexte d'application NEL).
• nel_export : code C++ de la boite de dialogue d'export et code d'export des différents formats NEL.
• nel_mesh_lib : code C++ spécifique pour la conversion des représentations internes de surfaces de 3D Studio Max vers des maillages au format NEL.
• nel_patch_converter : cf. ci dessous.
• nel_patch_edit : cf. ci dessous.
• nel_patch_edit_adv : cf. ci dessous.
• nel_patch_lib : cf. ci dessous.
• nel_patch_paint : cf. ci dessous.

Code à analyser : en 3D les surfaces sont modélisées par un maillage de triangles. Le concept de patch fait référence à l'utilisation des courbes bezier ou autres pour modéliser une surface. Même si au final l'affichage se fera par dessin d'un maillage de triangles (en calculant les positions des sommets des triangles via les valeurs de ces courbes à ces points), l'utilisateur manipule directement un courbe. Ce code C++ semble offrir des fonctionnalités pour faciliter la manipulation de ces surfaces dans 3D Studio Max.

• nel_vertex_tree_paint : Pas encore analysé¹⁾
• scripts : maxscript .ms à lancer via la commande du menu run script command. Cf. la liste en annexe
• tile_utility : pas clair, code de gestion des banques de textures ?²⁾

Extrait du code code/nel/tools/3d/plugin_max/nel_export/nel_export.cpp. Il définit les formats de fichiers sélectionnables dans la boite de dialogue d'export :

CNelExportClassDesc CNelExportDesc;
ClassDesc2* GetCNelExportDesc() {return &CNelExportDesc;}

static const char *zoneFilter="NeL zone file (*.zone)\0*.zone\0All files (*.*)\0*.*\0";
static const char *meshFilter="NeL shape file (*.shape)\0*.shape\0All files (*.*)\0*.*\0";
static const char *collisionFilter="NeL collision file (*.cmb)\0*.cmb\0All files (*.*)\0*.*\0";
static const char *animModelFilter="NeL model animation file (*.anim)\0*.anim\0All files (*.*)\0*.*\0";
static const char *SWTFilter="NeL Skeleton Weight Template file (*.swt)\0*.swt\0All files (*.*)\0*.*\0";
static const char *InstanceGroupFilter="NeL Instance Group file (*.ig)\0*.ig\0All files (*.*)\0*.*\0";
static const char *skeletonFilter="NeL Skeleton file (*.skel)\0*.skel\0All files (*.*)\0*.*\0";
static const char *vegetableFilter="NeL Vegetable file (*.veget)\0*.veget\0All files (*.*)\0*.*\0";
static const char *lodCharacterFilter="NeL LodCharacter file (*.clod)\0*.clod\0All files (*.*)\0*.*\0";

Extrait du code code/nel/tools/3d/plugin_max/nel_export/nel_export_script.cpp. Ce code définit les fonctions C++ accessibles au langage de script maxscript de 3D Studio Max.

/*===========================================================================*\
 |      Define our new functions
 |      These will turn on texture map display at all levels for a given object
\*===========================================================================*/

def_visible_primitive ( export_shape,           "NelExportShape");
def_visible_primitive ( export_shape_ex,        "NelExportShapeEx");
def_visible_primitive ( export_skeleton,        "NelExportSkeleton");
def_visible_primitive ( export_animation,       "NelExportAnimation");
def_visible_primitive ( export_ig,              "NelExportInstanceGroup");
def_visible_primitive ( export_skeleton_weight, "NelExportSkeletonWeight");
def_visible_primitive ( view_shape,             "NelViewShape");
def_visible_primitive ( test_file_date,         "NeLTestFileDate");
def_visible_primitive ( export_vegetable,       "NelExportVegetable");
def_visible_primitive ( reload_texture,         "NelReloadTexture" );
def_visible_primitive ( export_collision,       "NelExportCollision" );
def_visible_primitive ( export_pacs_primitives, "NelExportPACSPrimitives" );
def_visible_primitive ( export_lod_character,   "NelExportLodCharacter" );
def_visible_primitive ( node_properties,        "NelNodeProperties" );
def_visible_primitive ( mirror_physique,        "NelMirrorPhysique" );
def_visible_primitive ( get_file_modification_date, "NeLGetFileModificationDate" );
def_visible_primitive ( set_file_modification_date,  "NeLSetFileModificationDate" );

Pipeline 3D Studio Max

A ce jour, les fichiers .max servent pour la génération des fichiers NEL natifs suivants : .anim, .clodbank, .cmb, .ig, .pacs_prim, .shape, .skel, .swt, .zone, .veget.

• .shape :  un fichier 3D NEL contenant un modèle de maillages (mesh / surface) 3D. Le maillage est la brique de base pour construire des objets 3d. NEL sait manipuler plusieurs types de maillages : simple, avec texture, avec LOD, système de particles, surface eau, etc…
• .veget : maillage basique composé de quelques polygones comme support aux textures de micro-végétation (version spécifique de .shape).
• .ps : fichier 3D NEL contenant un “système de particules”. De même que pour les .veget, les .ps ne sont que des fichiers .shape.
• .skel : fichier 3D NEL décrivant le squelette utilisé pour déformer les maillages 3D lors des animations.
• .swt : fichier 3D NEL des contraintes (à valider)³⁾ associées à un squelette.
• .anim : fichier 3D NEL contenant des pistes nommées d'animation. Chaque piste décrit les modifications (rotation, translation, mise à échelle, etc…) appliquée aux nœuds d'un squelette pour une animation donnée.
• .clodbank : (Character LOD Bank) fichier 3D NEL contenant une banque de sprites des personnages pour un affichage rapide lorsqu'ils sont éloignés (format similaire à celui de quake 1).
• .zone : fichier 3D NEL représentant une portion de terrain de 160x160m.
• .pacs_prim : fichier 3D NEL contenant un ensemble de primitives PACS (Description de Boite, Cylindre : taille, rayon, hauteur, position, etc…) .À priori ces objets basiques servent à calculer les collisions, lorsqu'un avatar se déplace on va comparer sa position avec ces ensembles d'objets basiques. Donc la pipeline génère cet ensemble d'objets simplifiés à partir de la carte du terrain et de son contenu.
• .cmb : une liste de primitives géométriques pour calculer les collision avec les maillages 3d.

• Cas particuliers : .dds : est un format de texture (bitmap) compressé géré de manière hardware⁴⁾ par les cartes 3D modernes. Cependant lors de la modélisation 3d on utilisera plutôt le format .tga ou .png. Les textures seront converties/compressées au format .dds par la suite indépendamment du l'outil de modélisation.

Étude au cas par cas

3.2.1. Système de particules .ps

Définition : Un système de particules est une technique d'animation 3D qui utilise un grand nombre de petits sprites (ou autres objets graphiques) pour simuler des phénomènes semi-chaotiques. Ainsi dans Ryzom des phénomènes tels que feu, bancs de poissons, effet de sort, fumée, neige, feux d'artifices sont simulés par cette technique.

Pour faire simple, utilisons un exemple de neige. Tout système de particules possède une entité émettrice (ici le rectangle haut d'un cube modélisant l'espace où il neige). Cette entité génère les particules (ici des sprites représentants des flocons de neige) et pas nécessairement au même moment. Chaque particule évoluera selon différents paramètres (vitesse, gravité, durée de vie…) dans l'espace et dans le temps.

Implémentation de l'export .ps sous Blender : l'éditeur Objet Viewer QT issu du Google summer code intègre à présent un éditeur de particules. Il n'est plus nécessaire de prévoir ce cas de figure dans le projet.

Les maillages .shape et les fichiers .ig

Un triangle est une primitive formée par trois sommets (vertices, vertex). Il s'agit de la surface 2D avec le plus petit nombre de sommets et constitue la primitive de base utilisée par les cartes graphiques 3d modernes. Ainsi les scènes 3d sont en fait constituées de maillages de triangles. Ce maillage est facile à spécifier via un tableau de triplet (vertices) décrivant les sommets de ces triangles. Exemple de la figure ci-dessous, le tableau de sommets pour le GL_TRIANGLE_STRIP serait : { V₀(x₀,y₀,z₀), V₁(x₁,y₁,z₁), … , V₆(x₆,y₆,z₆) }

Au final, toute application 3D manipule ces tableaux de sommets que l'on nomme “Vertex Array” ou “Vertex Buffer”. À charge à la carte graphique (ou la librairie OpenGL, DirectX, etc…) de calculer la projection de ces surfaces composées de milliers de petits triangles (comme la théière ci-dessus) sur un plan 2D représentant nos écrans.

Il va sans dire que la réalité est plus complexe, il faut notamment compléter ces tableaux de vertex par des informations de rendu : la position, l'échelle, la couleur diffuse, la normale, la texture associée à cette surface, etc. La brique de base de toute application 3D reste cependant ce fameux tableau de sommets spécifiant les surfaces des modèles 3D.

La classe NEL dénommée IShape est une abstraction de cette notion de maillage. Un fichier NEL .shape permet et la sauvegarde sur disque d'un objet NEL IShape (un .shape est la sérialisation d'un IShape), c'est-à-dire un maillage de vertex représentant une surface 3D, la/les texture(s) associée(s), ainsi que d'autres informations de rendu. Notons que les textures ne sont pas sauvegardées dans le fichier .shape, elles apparaissent sous la forme de références (c'est-à-dire les noms des fichiers images : .tga, .png ou .dds).

Un fichier .ig (Instance Group) est juste un rassemblement dans un même fichier de plusieurs “shape” (maillages).

Cf. dans nel/3d

class CMeshBase : public IShape
class CMesh : public CMeshBase
class IMeshGeom : public NLMISC:IStreamable
class CMeshMRMGeom : public IMeshGeom
class CMeshBaseInstance : public CTransformShape
class CSkeletonShape : public IShape
class CFlareShape : public IShape
class CLodCharacterShape
class CParticleSystemShape : public IShape
class CSegRemanenceShape : public IShape  /** Shape for the remanence of a segment (sword stroke ..) */
class CTransformShape : public CTransform  /* A transform which "is an instance of"/"point to" a Ishape. */

Les zones du terrain « .zone »

Si dans la théorie on doit fournir à la carte graphique les surfaces à dessiner sous la forme d'une suite de triangles, dans la pratique, ils sont rarement sauvegardés sous la forme d'une série de sommets. Parfois il est plus efficace de les calculer dynamiquement. Ainsi on peut définir ces surfaces à partir de courbes mathématiques. La plus employée dans ce cas est la courbe de Bézier. De telles surfaces sont appelées dans le jargon 3D des “patches”. Pour faire le parallèle avec les images 2D : une surface définie par un tableaux de vertex est l'équivalent d'une image bitmap, une surface type patches est l'équivalent d'une image vectorielle. Ainsi par exemple les surfaces représentant le terrain sont formées de patche. Ce qui permet d'adapter le nombre de triangle du maillage en fonction de la distance, assurant un rendue toujours lisse même de près.

Export vers blender

Exporter une scène 3d construite dans Blender vers le format NEL afin d'être réutilisée par le moteur RyzomCore. Cela concerne :

• Les surfaces3d (shape) des objets [ avec leur textures, info d'illumination, etc..]
• Les structures squelettes utilisées pour l'animation . [.squel]
• Les animations (enregistrement des séquences d'animation des squelettes)
• Les objets Ligo (brique de base de terrain représentant un carré de 128×128 m).
• Le système de particule
• Les vagues ? (modèle de surface de l'eau)

Aide à la création de modèles 3d conformes aux contraintes de NEL

Scripts d'initialisation de la scène 3d pour des cas particuliers. Liste des scripts existant sous 3dsmax. Apparemment ces scripts ajoutent des boites de dialogues pour manipuler des éléments de la scène, permettant de saisir des données spécifiques aux modèles NEL.

Voir la sérialisation dans NEL.

Prérequis

Essentiel

• Maîtrise du langage python et C++ : une personne maîtrisant l'un des deux langages peut facilement basculer sur l'autre et monter en compétence. C'estt moins vrai en partant de python vers C++, mais c'est moins grave car il programmera en python. Les connaissances C++ me paraissent nécessaires car il devra interfacer python avec la bibliothèque NEL3D. Si quelqu'un peut lui compiler une version de NEL utilisable avec python, il aura surtout besoin d'être capable de l'utiliser, pas forcément de programmer
• Connaissance de base en modélisation 3d : maîtrise des concepts de base d'OpenGL (surface, texture, couleur, …). C'est un prérequis fondamental, au risque de perdre beaucoup de temps et de passer à côté de choses essentielles, j'accepterai⁶⁾ de prendre quelqu'un programmant en java et ne connaissant pas C++/python s'il maîtrise ces concept mais pas l'inverse.

Vivement Souhaité

• Maîtrise d'un outil de modélisation 3d : Blender, 3dsmax ou autre. C'est un application directe des connaissances du point précédent, et de toute façon il faudra manipuler blender/3dsmax.

Souhaité optionnel

• Connaissance de Blender python. Une connaissance préalable des représentations internes de Blender ferait gagner du temps.</wrap>
• Connaissance de Maxscript. Une personne maîtrisant les concepts de programmation objet sera capable de de comprendre globalement ce que font les scripts Maxscript.

État des lieux

Configuration d'un espace de travail

• Installation des assets ryzom
• OVQT pour visualiser les formats NEL exportés +les autres outils NEL
• Blender
• 3D Studio Max ( pas forcément obligatoire mais serait une grosse aide)

NEL

Lister les éléments de scène 3d manipulables par la bibliothèque NEL avec leurs caractéristiques

Lister les formats de fichiers utilisés par la bibliothèque pour sérialiser des éléments 3d (.ps .shape .squelette, etc…)

Inside NEL

• http://dev.ryzom.com/projects/ryzom/wiki/NeL_Files_and_Serialisation
• https://ryzomcore.atlassian.net/wiki/display/RC/NeL+3D
• https://ryzomcore.atlassian.net/wiki/display/RC/NeL+Ligo

Blender

Faire un tour des caractéristiques de l'outil Blender, et s'assurer qu'il peut manipuler tous les types d'objets de NEL (en général c'est plutôt l'inverse, il faudra plutôt à veiller à ne pas utiliser certaines caractéristiques de Blender dans les objets qui ne sont pas exploitables par NEL).

Développement

Exemple de script basique d'export du manuel de blender
http://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro/Advanced_Tutorials/Python_Scripting/Export_scripts

Un exemple concret et expliqué d'un script python d'export pour Blender. L'auteur démonte un à un les mécanismes pour parcourir les représentations internes des objets 3D de Blender et la manière de les enregistrer dans un fichier d'export.

1. http://brucesutherland.blogspot.fr/2012/05/blender-262-writing-export-script.html
2. http://brucesutherland.blogspot.fr/2012/05/blender-262-writing-export-script-using.html
3. http://brucesutherland.blogspot.fr/2012/05/blender-262-writing-export-script_21.html
4. http://brucesutherland.blogspot.fr/2012/05/deciphering-binary-files.html

Annexes

Caractéristiques des objets 3d NEL d'après les fichiers README du plugin 3DSMax-NEL

( essayer d'ajouter ici des liens vers wikipédia ou des introductions bien faites mais en anglais⁸⁾)

Animation

(cf. max_animation_support.txt)

Animation des nœuds du squelettes [inode]

• Position
• Rotation
• Mise à échelle [uniquement local au nœud de l'animation

Animation du matériel (textures)

• Couleur d'ambiance
• Couleur diffuse
• Couleur spéculaire
• Couleur d'illumination
• Opacité

L'interpolation entre deux états de l'animation peut se faire de manière :

• linéaire [mouvement entre deux positions, rotation, mise à échelle, interpolation entre deux couleur … ]
• Bézier [idem]
• TCB [??]

Lumières

(cf. max_ligh_support.txt)

Modèles de lumières supportés pour les objets 3d

• Lumière d'ambiance globale
• Lumière omnidirectionnelle
• Lumière type Spot
• Lumière type directionnelle

Paramètres de ces lumières pris en compte par NEL

• Couleur
• Couleur diffuse
• Couleur spéculaire
• Couleur d'ambiance
• Multiplicateur [??]
• HotSpot, FallofSpot [??]
• DistanceInitiale, DistanceFin et valeur associée pour l’atténuation de la lumière.

Lighmap

(cf. max_lightmap_support.txt)

Il s'agit d'un texture qu'on applique à un objet 3d pour simuler des effets de lumière : ombres,…

Caractéristiques prises en compte :

• Omni and spot light only
• Attenuation far
• Exclude mesh from light
• Cast Shadow on light and cast/receive in object properties
• Spot texture projector
• Ambient only
• Multiply factor
• Double sided
• Opacity in texture
• Stained glass in texture through NeL material

Matériel

(cf. max_matérial_support.txt)

Il s'agit des informations concernant la couleur des objets. Exemple : mapping d'une texture sur le modèle 3d, définition de la couleur de chaque sommet de la surface, etc… Éléments supportés par NEL :

• Lightmap 
• Color vertex
• Alpha vertex
• multitexturing

Caractéristiques prises en compte :

• Ambiant color
• Diffuse color
• Specular color
• Self illumation value (pseudo)
• Self illumation color (pseudo)
• Opacity
• Shininess (pseudo)
• Glosness (pseudo)
• Diffuse texture
• Opacity texture. If opacity texture and diffuse texture are used, NeL try to use the alpha channel of the diffuse texture as opacity map.
• Double sided
• You can use crop if you don't repeat the texture.
• You can use crop and repeat the texture on U if the U crop is full (0 → 1).
• You can use crop and repeat the texture on V if the V crop is full (0 → 1).
• Extended parameters transparency type (filter or additive)
• Specular is used throught cube environnement mapping (use composite to give the 6 faces a unique texture)

Matériel utilisé pour le rendu de l'eau

(cf. nel_water_material.txt)

Une surface “Eau” est modélisée par un polygone convexe sur lequel on plaque des textures. Le package “texture eau de NEL” est constitué de :

• Texture 1 : Un « environment map » réfléchit par l'eau (texture représentant un projection du ciel)
• Texture 2 : texture alternative à la texture 1
• Texture 3 : Similaire à texture 1 mais vu des sous la surface de l'eau
• Texture 4 : Similaire à texture 2 mais vu des sous la surface de l'eau
• Texture 5 : Une texture « heightmap » utilisée pour déformer le « environnement map » de l'eau
• Texture 6 : Similaire à 5
• Texture 7 : Alpha et couleurs pour moduler la coulrur et la transparence de l'eau

Liste des scripts présents dans le plugin 3DSMax/NEL

• db_cleaner.ms
• db_erase_mesh.ms
• db_shooter.ms
• extrude_water.ms
• nel_add_name_ref_scale.ms
• nel_assets_png.ms
• nel_assets_png_batched.ms
• nel_assets_png_database.ms
• nel_batched_mergesave.ms
• nel_batched_script.ms
• nel_copy_biped_figure_mode.ms
• nel_create_matrix.ms
• nel_ligoscape.ms
• nel_mat_converter.ms
• nel_mirror_weights.ms
• nel_move_animation.ms
• nel_node_properties.ms
• nel_old_zone_to_ligo.ms
• nel_rename.ms
• nel_repair_xref.ms
• nel_select.ms
• nel_select_ig.ms
• nel_utility.ms
• nel_xref_building.ms
• reload_textures.ms

Liste des scripts d'initialisation du plugin « 3DSMax-NEL »

Pour certains de ces scripts, il s'agirait de définir des boites de dialogue afin de manipuler les caractéristiques des objets utiles à NEL. À confirmer par un programmeur de maxscript.

• nel_flare.ms
• nel_light.ms
• nel_material.ms
• nel_material.ms.v1
• nel_material.ms.v11
• nel_material.ms.v2
• nel_material.ms.v3
• nel_material.ms.v5
• nel_multi_set.ms
• nel_pacs_box.ms
• nel_pacs_cylinder.ms
• nel_ps.ms
• nel_swt.ms
• nel_wave_maker.ms

Informations tirées de la ML OpenNeL

Ce sont des extraits d'une vieille ML, les informations peuvent être sujet à modification/réinterprétation, à vérifier. Néanmoins on y trouve énormément d'informations de base sur le moteur de jeu.

Usage des library NeL

Export des zones de décor