{DU:API}

Download

DU lua Sandbox

Version 0.7 (alpha)

projet open source
sous license GNUv3

compatible Windows 7-10


Download executable

GitHub



Donation

Pour encourager l'auteur ou contribuer aux graphiques, cliquez le lien ci-dessous. Merci!

DU lua sandbox
Une sanbox lua open source pour dual universe.

DU Lua Sandbox API


Ce document est un tutoriel pour l'outil de développement DU lua sandbox. Il s'agit en fait d'un api permettant le développement d'applications LUA dans l'univers du jeu Dual universe.


J'ai crée cet API en 2 parties.

1 - une api LUA contenant (presque) toutes les classes de DU. (duElementAPI)
2 - une api JAVA contenant une sandbox LUA dual universe. (duJavaAPI)

La sandbox permet d'émuler la quasi-totalité des éléments du jeu, des écrans utilisant le html5 (incluant le svg) allant jusqu'à la base de donnée interne (database.getPlayer, database.getConstruct, databse.getElement). Il imite le fonctionnement en temp reel de plusieurs éléments du jeu.

Il est simple à utiliser. La configuration ce fait à partir de fichier lua nommé Preload (voir la section preload de ce document).

Le code est en open source. Il est accessible via ce github



A qui s'adresse cet outil.

L'api à été conçu pour travailler sur des écrans de dual universe (L'élément in game).

Il a été conçu pour travailler en mode "projet" et permet de bénéficier d'un système de fichier. La versatilité du fichier de chargement (preload) permet de créer des librairies de fonctions et de faire du code réutilisable. Les scripts sont automatiquement intégrés lors de l'export (texte ou json). La sandbox à particulièrement été conçu pour concevoir des applications ingame ou même des jeux. L'élément databank est déjà implémenté à 100%.

Il n'est pas encore assez avancé pour être efficace au niveau des systèmes de vol, mais il le sera probablement sur le long (avec de l'aide).


Retourner à l'index



Installation


Décompressez le contenu du fichier DULuaSandbox.zip à l'emplacement de votre choix. le répertoire ./src et son contenu est requis à l'exécution de la sandbox.



Retourner à l'index



Utilisation en mode standalone




pour lancer la sandbox. Cliquez sur dusandbox.exe

La boite a outil de l'application permet de relancer le script en appuyant sur "Reload (F9)" ou de charger un nouveau script par la bar de lancement. "RUN (F5)"


Utilisation dans Eclispe LDT (mode interpreteur)


La sandbox peut être utilisé comme interpréteur LUA dans Eclipse LDT.



créez un lunch configuration pour chaque fichiers de preload. Cliquez sur le tabb du fichier preload puis cliquez sur RUN (ctrl-F11) pour lancer le projet.


Retourner à l'index




Captures d'écrans

Databanks fonctionnelle


Exemple de système d'inventaire


Création d'interface utilisateur avec souris fonctionnelle.


Timers et update qui permet d'animer des svg en temps réel.


Hud fonctionnelle


Paufiner votre code grace des fonctions de débuguage


Imitation du codex lua de dual universe


Des exemples de code




PRELOAD



Le preload est un fichier de configuration en LUA. Il configure l'environnement et ajoute les éléments à la sandbox (door, unit, databank....)

Par standard, le fichier de preload est nommé [nomprojet]_load.lua. Il est utilisé pour démarrer votre projet.

Le preload charge les fichiers LUA pour les évènements (start, tick, stop...) relié aux scripts. Il sert aussi pour configurer la sandbox et rajouter des joueurs et constructs.

Toutes les fonctions du LUA sont disponible. Y compris les fonctions de lecture/ecriture du système de fichier et les fonction lua "dofile" et load.

À la fin du preload, seul les configurations acquise et les éléments ajoutés sont conservés. La session LUA est remise à zéro puis la sandbox est lancée (avec l'environnement du jeu).

Évidemment, les fonctions utilitaires liées au chargement du preload ne sont pas utilisable dans l'environnement de jeu.

Notez qu'il y a une librairie json disponible dans la session du preload. (https://github.com/rxi/json.lua)


Example de fichier preload
showOnScreen(1)
verboseLua(1)
verboseJava(0)

-- scripts de l'unit
UnitStart = [[
screen1.activate()
screen1.addContent(0,0,"hello world")
]]

UnitStop = "print('closing')"

-- ajout de l'unit
obj = Unit(UnitStart, UnitStop)

-- ajout d'un écran
obj = ScreenUnit('screen1', 1024, 612)
moveElement(obj, 300, 5)

Retourner à l'index


Fonctions du preload



Retourner à l'index



Outils
showOnScreen(screenId)
Définit l'écran de démarrage de la sandbox lua (en dual screen).
Argument Type Description
screenId
[0,1]
numéro de l'écran physique

verboseLua(status)
Affiche ou non les messages du debugger lié au LUA.
Argument Type Description
status
[0,1]
1 pour activer les messages lua

verboseJava(status)
Affiche ou non les messages du debugger lié au Java.
Argument Type Description
status
[0,1]
1 pour activer les messages java

texte = loadScript(fichier)
Charge un fichier texte. Que ce soit un script lua ou une image svg. Le fichier est aussi ajouté à la liste des fichiers éditable accessible par le menu Edit.
Argument Type Description
fichier
string
fichier LUA à charger.

Valeur de retour Description
texte fichier texte chargé.

abort(msg)
Cancel l'exécution du script et affiche un message dans un popup.
Argument Type Description
msg
string
Message à afficher.

die(msg)
Cancel l'exécution du script et affiche un message dans la console.
Argument Type Description
msg
string
Message à afficher.

moveElement(id, x, y)
Déplace le widget de l'élément [id] à l'emplacement x/y. Par défaut les éléments sont placés de haut en bas en partant de la gauche.
Argument Type Description
id
int
Id de l'élément à déplacer
x
int
Position X de la nouvelle emplacement.
y
int
Position Y de la nouvelle emplacement..

pause(temps)
Fait une pause de [temps] ms.
Argument Type Description
temps
int
durée de la pause en ms.

Retourner à l'index



Configuration

addChannel(id, channel, script)
Associe le script à au canaux des éléments emitters/receivers. (voir emitter_load.lua)

Nécessaire à l'utilisation des emitters/receivers.
Argument Type Description
id
id
L'id de l'élément "receiver" qui recevra les messages.
channel
string
Nom de canal du message
script
string
Le script à assigner à l'event.

setupDatabase(player, construct, MasterPlayerId)
Configure la base de donnée interne de la sandbox. Nécessaire pour les fonctions "database", les radars et la fonction getMasterPlayerId().
Argument Type Description
player
player array
array contenant les informations des joueurs. (voir rubrique "dummy players")
construct
construct array
array contenant les informations des constructs. (voir rubrique "dummy constructs")
MasterPlayerId
int
Id du joueur actif (joueur ayant activé l'unit) selon l'array "player".

setHUD(script, x, y, width, height)
Initialise un écran hud. Permet de lier le script pour l'événement update.
Argument Type Description
script
string
Script de l'événement update. optionnel.
x
int
Position x de l'écran hud. optionnel.
y
int
Position y de l'écran hud. optionnel.
width
int
largeur. optionnel.
height
int
Hauteur. optionnel.

setupTimer(id, nom, script )
Crée et configure un timer (tick) et associe le script au timer lié à l'Unit [id]. Le timer doit être activé dans les scripts avec la commande setTimer(nom, délais).
Argument Type Description
id
id
Id de l'unit servant à la maintenance.
nom
string
Nom du timer à utiliser pour la fonction setTimer
script
string
Script LUA à utiliser pour le timer.

Retourner à l'index



Éléments


id = ButtonUnit(name, label, script)
Initialise un élément button.
Argument Type Description
name
id
nom de l'élément.
label
string
Libellé du bouton.
script
string
Script LUA à utiliser pour l'event du bouton.

Valeur de retour Description
id Id de l'élément crée.

id = ContainerUnit(name)
Initialise un élément container.
Argument Type Description
name
string
nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = Core(size, constructType, g, selfConstructId)
Initialise un élément core.
Argument Type Description
size
int
Taille du core par facteur de 16. (xs = 16)
constructType
string
dynamic ou static
g
float
La gravitée local.
selfConstructId
id
Assigne le core à un construct. L'id correspond aux constructs de la base donnée interne (voir SetupDatabase(...)).

Valeur de retour Description
id Id de l'élément crée.

id = DataBankUnit(name)
Initialise un élément DataBank.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = DoorUnit(name)
Initialise un élément Door.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = EmitterUnit(name)
Initialise un élément Emitter.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = ForceFieldUnit(name)
Initialise un élément ForceField.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = GyroUnit(name)
Initialise un élément Gyro.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = GyroUnit(name)
Initialise un élément LandingGear.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = LightUnit(name)
Initialise un élément Light.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = Navigator(name)
Initialise un élément Navigator.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = RadarUnit(name, range, scriptEnter, scriptExit)
Initialise un élément Radar. Nécessite l'initialisation de la base de donnée interne pour les dummy targets (voir SetupDatabase). voir l'exemple radar_load.lua pour plus de détail.
Argument Type Description
name
string
Nom de l'élément.
range
int
Distance de détection.
scriptEnter
string
Script de l'event Enter.
scriptExit
string
Script de l'event Exit.

Valeur de retour Description
id Id de l'élément crée.

id = ReceiverUnit(name)
Initialise un élément Receiver. Nécessite l'utilisation de addChannel(id, channel, script) pour assigner les scripts aux channels. (voir emitter_load.lua)
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = ScreenUnit(name, sizeX, sizeY)
Initialise un élément Screen. La taille des écrans est normalement de 1024x614. Vous pouvez cependant utiliser les annotations vw et vh pour réduire la taille de l'écran.
Argument Type Description
name
string
Nom de l'élément.
int
string
Dimension horizontal de l'écran.
int
string
Dimension vertical de l'écran.

Valeur de retour Description
id Id de l'élément crée.

id = SwitchUnit(name)
Initialise un élément Switch.
Argument Type Description
name
string
Nom de l'élément.

Valeur de retour Description
id Id de l'élément crée.

id = Unit(scriptStart, scriptStop)
Initialise un unit (programming board). Fonctionne avec setupTimer(unitId, timerName, script) pour l'assignement des scripts aux timers.
Argument Type Description
scriptStart
string
Script à associer à l'event start.
scriptStop
string
Script à associer à l'event stop

Valeur de retour Description
id Id de l'élément crée.

Retourner à l'index



Exemples



Des exemples de code source sont disponible dans le répertoire de l'application.


Retourner à l'index



Exporter un script



Les commandes d'exports de la toolboar, permet d'accéder à une version du script LUA pouvant facilement être copié vers l'éditeur de Dual Universe.

L'export compile toute les fichiers .lua du projet (librairies, événements...) en un seul fichier.

La fonction d'exports de l'api permet d'accéder au code source de l'API LUA. Il peut parfois vous permettre de débuguer vos scripts et peut permettre de comprendre le fonctionnement interne de l'API.


Vous pouvez aussi exporter en JSON. L'implémentation n'est pas encore complète (C'est dans le haut de la liste de prioritée). Bientôt, vous pourrez copier directement, la string JSON dans Dual universe. (C'est déjà possible avec plusieurs des exemples fourni (incluant visitor_load et flymart2).)
Retourner à l'index



Dummy constructs



Les dummy constructs servent à remplir la base de donnée interne du jeu. Que ce soit pour la database de DU (getPlayer(), getConstruct()) ou les radars.

Pour activer la base de donnée interne, vous devez utiliser la fonction SetupDatabase du fichier preload.

les arrays suivent une structure assez simple.


Exemple d'initialisation de dummy players et de dummy constructs:
playerList = {} -- also used as owners list
playerList[1] = {id = 0, name = 'unreachable', worldPos = {0, 0, 0}}
playerList[2] = {id = 1, name = 'Nmare418', worldPos = {0, 0, 0}}

constructList = {}

-- Static construct
constructList[1] = {id = 1,
 owner = 7,
 name = 'Base 1',
 ctype='static',
 pos = {133, -6233, 66},
 size = {115, 134, 122},
 speed = {0, 0, 0},
 mass = 2101.323}

-- moving construct
constructList[2] = {id = 2,
 owner = 2,
 name = 'Ship 1',
 ctype='dynamic',
 pos = {4353, 3233, 59},
 size = {15, 6, 12},
 speed = {25, 34, 0},
 mass = 12.43}

-- unreachable (player offline)
constructList[3] = {id = 2,
 owner = 0,
 name = 'Ship 2',
 ctype='dynamic',
 pos = {4353, 3233, 59},
 size = {15, 6, 12},
 speed = {0, 0, 0},
 mass = 12.43}

-- setup the internal database. playerlist, constructlist, main player
setupDatabase(playerList, constructList, 1)


Retourner à l'index



BD SQL interne (H2)



Les dataBanks utilisent un système de base de donnée interne. Il est semblable à des base de donnée relationnelle (mysql, oracle, sql server...), mais , mais tiens en mémoire.

Cet outil vous permet de maintenir des bases de données. De copier des tables, copier des données et d'effacer directement le contenue des databanks. Il peut permettre d'exporter des données.

Notez que le nom de l'élément est aussi le nom de la base de donnée dans H2. Si vous nommez les dataBanks avec le même nom dans 2 projets différents, ils utiliseront la même source de donnée dans la base de donnée H2.

Documentation de H2 H2 Database Engine

Example de requête:
SELECT ID, COUNT(*) FROM TEST GROUP BY ID;
SELECT * FROM DB1;


Notes:

Retourner à l'index



Bugs




Le bug est causé par l'objet web utilisé. Les widgets avec du html, doivent être réinitialisés après la dé-iconification. Le bug sera bientôt corrigé


Retourner à l'index



A faire (todo)



Liste des objectifs à cour et moyen terme (par priorité): 

Liste des objectifs à long terme: 



Retourner à l'index

Crédits


Conçu par Stéphane Boivin aka Nmare418 (Discord: nmare418#6397).

Développement Java/Lua par Stéphane Boivin.

Illustrations par l'artiste Valérie Dandois (https://valeriedandois.wixsite.com/valdandois)


Fureteur HTML: DJNativeSwing par Christopher Deckers - http://djproject.sourceforge.net/ns/index.html

Interpreter LUA: LuaJ par James Roseborough, Ian Farmer - luaj.org

Base de donnée: H2 par Thomas Mueller, HSQLDB Group - www.h2database.com

Json JAVA: json-simple par Yidong Fang - https://github.com/fangyidong/json-simple

Json LUA: jsonv par rxi - https://github.com/rxi/json.lua




Retourner à l'index