Script - Xtreme3D

Initialisation
La 3D de Script requiert l'importation des fichiers DLL Xtreme3D.dll et ode.dll dans le répertoire res/dll/ du projet Script concerné.
Ces DLL sont téléchargeables ici.
(Pendant l'exécution du code, le fichier ode.dll est copié à la racine du projet. Ce fichier peut être supprimé s'il vous dérange, mais sera automatiquement regénéré.)

Pour les curieux:
Xtreme3D est créé à partir du célèbre moteur 3D OpenGL, connu pour être utilisé pour la réalisation de nombreux jeux vidéo.
ODE est quant à lui utilisé pour le calcul de la physique 2D et 3D.

X3D_start(pakfile);
Initialise le moteur 3D de Script. Pakfile est le chemin du fichier .pak contenant les textures du jeu. Si cet argument n'est pas renseigné, Script ira chercher vos textures dans le dossier res/spr/.

X3D_end();
Arrête le moteur 3D de Script, permettant ainsi d'allouer la totalité des ressources aux fonctions 2D classiques. Si un jeu 3D s'arrête sans avoir appelé cette fonction, Script s'en chargera.

Matériaux

X3D_material_create(filename, transparent, scalex, scaley);
Importe l'image filename comme matériaux 3D depuis le fichier pak ou le dossier res/spr/ (voir fonction X3D_start();). Cette fonction permet aussi de déterminer si la transparence doit être gérée (valeur booléenne), et les répétitions de texture sur l'axe x ou y. Les trois derniers arguments sont facultatifs. La fonction retourne l'identifiant de la texture importée.

Objets

Les objets sont des entités invisibles caractérisées par une position (x, y, z) une rotation (rx, ry, rz) dans l'espace. En 3D, l'axe Y symbolise la hauteur, mais il est possible d'utiliser un autre axe.

X3D_object_create(x, y, z, parent);
Créé et retourne un nouvel objet à la position x, y, z. L'objet peut avoir un parent, et ainsi se servir de sa position comme repère dans l'espace (la position (0, 0, 0) devient la position de l'objet parent). Tout les arguments sont facultatifs (les arguments de position auront zéro pour valeur par défaut).

X3D_object_show_axes(object, enable);
Affiche/masque les axes X, Y et Z de l'objet object.

X3D_object_set_culling(object, enable);
Masque/Affiche l'objet s'il est hors camera. Cette option peut améliorer les performances. Elle est activée par défaut sur tout les nouveaux objet créés.

X3D_object_rotate(object, rx, ry, rz);
Incrémente les valeurs rx, ry, et rz aux rotations de l'objet object.

X3D_object_move(object, distance);
Applique un déplacement avant-arrière de la distance renseignée à l'objet object. Attention, cette fonction téléporte l'objet, une grande distance peut encastrer l'objet dans un autre malgré la gestion des collisions.

X3D_object_strafe(object, distance);
Applique un déplacement gauche-droite de la distance renseignée à l'objet object. Attention, cette fonction téléporte l'objet, une grande distance peut encastrer l'objet dans un autre malgré la gestion des collisions.

X3D_object_set_position(object, x, y, z);
Positionne l'objet object à la position (x, y, z) par rapport à son repère (qui est la position de l'objet parent, ou le point (0, 0, 0) si l'objet en question n'a pas de parent).

X3D_object_get_position(object, dir);
Retourne la coordonnée dir de l'objet object. Dir peut avoir les valeurs 'x', 'y' ou 'z' (en majuscules ou minuscules).

Formes

Les formes sont des objets ayants une apparence graphique, et diverses caractéristiques propres à cette apparence (taille, texture, transparence, gravité, collisions, etc).

X3D_plane_create(x, y, z, w, h, scalex, scaley, multiquad, texture, parent);
Créé et retourne un nouvel objet plan à la position x, y, z de dimensions w et h. scalex et scaley permettent de déterminer le nombre de répétitions de l'affichage de la texture sur le plan. Texture est un identifiant de texture. L'argument parent est facultatif.

X3D_cube_create(x, y, z, w, h, d, texture, parent);
Créé et retourne un nouvel objet cube à la position x, y, z de dimensions w, h, d. Texture est un identifiant de texture. L'argument parent est facultatif.

X3D_sphere_create(x, y, z, r, texture, parent);
Créé et retourne un nouvel objet sphere à la position x, y, z de rayon r. Texture est un identifiant de texture. L'argument parent est facultatif.

Cameras

Les cameras sont des objets ayants la capacité de filmer la scène dans la direction vers laquelle elles sont orientées. Leur configuration est modifiable (proportions de l'image, portée visuelle, etc).
Elles ne suffisent pas à visualiser la scène car elles ne gèrent pas l'affichage de l'image sur l'écran (voir les vues).

X3D_camera_create(x, y, z, scale, parent);
Créé un nouvel objet camera à la position x, y, z de dimensions scale (rapport largeur/hauteur de l'affichage désiré) ayant le parent renseigné (l'argument parent est facultatif). La fonction retourne l'objet camera créé.

X3D_camera_set_scale(camera, scale);
Détermine les proportions du rendu de la camera. Sa valeur doit être le rapport largeur/hauteur de l'affichage désiré.

X3D_camera_set_depth(camera, depth);
Détermine la profondeur du champ de vision de la camera. Il s'agit de la distance à partir de laquelle les objets ne sont plus visibles. Une distance trop grande peut entrainer du lag. La valeur par défaut est 5000.

Vues

Les vues sont des rectangles 2D sur la fenêtre de Script dans lesquels sera affiché l'image filmée par une camera.

X3D_viewer_create(x, y, w, h);
Créé une nouvelle vue dont le coin supérieur gauche sera placé à la position (x, y) de l'écran, et dont la largeur et la longueur de l'image seront respectivement les valeurs w et h. La fonction retourne la vue créé.

X3D_viewer_set_camera(view, cam);
Connecte la camera cam à la vue view.

X3D_viewer_render(view);
Prend une photo depuis la camera connectée à la vue view actualisant ainsi le rendu.

X3D_viewer_set_background_color(view, color);
Définit la couleur color comme couleur d'arrière plan de la vue view.

X3D_viewer_set_vsync(view, enable);
Active/désactive la synchronisation verticale sur la vue view. Enable est une valeur booléenne.

X3D_viewer_set_lighting(view, enable);
Active/désactive la lumière sur la vue view. Enable est une valeur booléenne.

Souris

X3D_mouse_set_position(x, y);
Place la souris à la position (x, y) de l'écran.

X3D_mouse_show_cursor(bool);
Affiche/Masque le curseur de la souris (1=visible, 0=invisible).

X3D_mouse_get_x();
Retourne la coordonnée x de la position de la souris.

X3D_mouse_get_y();
Retourne la coordonnée y de la position de la souris.

Lumières

Les lumières sont des objets ayants la capacité d'éclairer la scène. Leur configuration est modifiable (couleur, portée, etc).
Couleur diffuse et couleur ambiante.

X3D_light_create(x, y, z, mode, parent);
Créé et retourne un nouvel objet lumière à la position x, y, z configuré avec le mode renseigné (lsSpot, lsOmni ou lsParallel). L'argument parent est facultatif.

X3D_light_set_shining(light, enable);
Permet d'allumer ou éteindre la lumière light selon la valeur booléenne enable.

X3D_light_set_diffuse_color(light, color);
Définit color comme couleur diffuse de la lumière light.

X3D_light_set_ambient_color(light, color);
Définit color comme couleur ambiante de la lumière light.

Ombres

X3D_set_shadow(enable);
Active/désactive la gestion des ombres pour les prochains objets créés.

Skydome

X3D_skydome_create();
Créé un skydome et retourne son identifiant.

X3D_skydome_set_sun_elevation(skydome, dir);
Définit la hauteur du soleil. Dir est l'angle déterminant la position du soleil. La valeur est comprise entre -90 et 90.

X3D_skydome_add_random_stars(skydome, nb, color);
Ajoute nb quantité d'étoiles de couleur color dans le ciel skydome.

Physique

X3D_update();
Actualise la position de tout les objets selon leurs caractéristiques physiques (transitions, rotations, conservation d'énergie cinétique, etc). La vitesse de la physique est à renseigner (0.098 correspond à la valeur de la gravité terrestre qui est de 9.80665 m/s-²). La valeur zéro arrête le temps et une valeur négative permet d'effectuer un retour approximatif dans le passé.

X3D_set_gravity(enable);
Active/désactive la soumission à la gravité des prochains objets créés.

X3D_set_collision(enable);
Active/désactive la gestion des collisions pour les prochains objets créés.

X3D_object_add_force(object, x, y, z);
Applique une force à l'objet object selon le vecteur spatial (x, y, z). L'énergie cinétique de cette force est conservée.
