Plugins

Mit dem Plugin-System von Visionaire Studio entwickelst du eigene Aktionsteile.

Plugins werden pro Projekt installiert. In einem neuen Projekt musst du sie also (erneut) installieren, auch wenn du sie schon in einem anderen Projekt verwendet hast. Über das Puzzle-Symbol in der Symbolleiste öffnest du den Plugin-Bereich und siehst alle installierten und installierbaren Plugins. Dort kannst du sie auch wieder deinstallieren.

Nach der Installation stehen dir die neuen Aktionsteile zur Verfügung: im Auswahldialog im Bereich „Custom“ und unten in der Liste der Aktionsteile in den Eigenschaften eines Aktionsteils.

Mitglieder der Visionaire-Community haben einige ihrer Plugins geteilt. Du kannst sie hier im Wiki herunterladen.

Ein Plugin installieren

1. Besorge dir die ZIP-Datei des Plugins (zum Herunterladen oder selbst gebaut).
2. Lege im Hauptordner deines Projekts (dort, wo die .ved- bzw. .veb-Datei liegt) einen Ordner „plugins“ an, falls es ihn noch nicht gibt.
3. Entpacke die Datei und kopiere den Ordner darin in den Ordner „plugins“.
4. Öffne dein Projekt in Visionaire und klicke oben rechts auf das Puzzle-Symbol.
5. Die Liste der verfügbaren Plugins öffnet sich. Klicke beim neuen Eintrag auf „Install“.
6. Speichere dein Projekt.

Ein Plugin entwickeln

Aufbau eines Plugins

Jedes Plugin ist ein Ordner mit bis zu vier Dateien, meist als ZIP-Archiv weitergegeben (siehe Bild). Bei der Installation entpackt man das Archiv selbst und kopiert den Ordner in das Verzeichnis „plugins“ (siehe Anleitung oben). Du kannst weitere Dateien in den Ordner legen, etwa eine README oder Ressourcen, die du brauchst. Die folgenden Dateien benötigt Visionaire aber, nur das Bild ist optional:

• Ordner Benenne den Ordner wie dein Plugin (so wie in der Datei config.ini angegeben).
• config.ini Die INI-Datei sagt der Engine (und den Nutzern), worum es in deinem Plugin geht.
• editor.lua Diese Lua-Datei richtet die Eingabefelder des Aktionsteils im Visionaire-Editor ein.
• image.png Optional ein PNG-Bild mit 128 × 128 Pixeln, das dein Plugin im Plugin-Bereich des Editors darstellt.
• player.lua Diese Lua-Datei enthält den Code, der läuft, wenn der Aktionsteil im Spiel ausgeführt wird.

config.ini

Hier eine Beispiel-INI aus dem Plugin „Hello World“ (Download unten). Sie enthält alle nötigen Einträge:

# config.ini

Name=Hello World
Author=Einzelkämpfer
Date=12.04.2023
Version=1.0
PluginVersion=1
Link=https://wiki.visionaire-tracker.net/wiki/Plugins
ActionParts=Print Hello World
Description=This plugin adds an action part to print the string "Hello, World!" to the log file.

• Unter Name steht der Name des Plugins. Er muss mit dem Namen des Plugin-Ordners übereinstimmen.
• Unter Author trägst du deinen Namen ein, unter Date das Datum der Erstellung oder Veröffentlichung (das Format wählst du selbst).
• Unter Version steht die Versionsnummer deines Plugins.
• PluginVersion gibt die Art des Plugins an. Der Wert muss „1“ sein, denn das ist derzeit die einzige Art in Visionaire Studio.
• Unter Link kannst du auf deine Website verweisen.
• Unter ActionParts stehen die Aktionsteile deines Plugins (durch Komma getrennt). Im Beispiel ist es nur einer namens „Print Hello World“, ein Plugin kann aber auch mehrere Aktionsteile anlegen. Der Name jedes Aktionsteils muss mit dem Namen in editor.lua und player.lua übereinstimmen. Unter diesem Namen erscheint er auch im Editor.
• Unter Description kannst du beschreiben, was dein Plugin macht.

Die Grundlagen: „Hello, World!“

Nach der INI-Datei registrierst du den neuen Aktionsteil für den Editor und für den Player.

In der Datei editor.lua bekommt die Funktion registerActionPart() zwei Argumente: zuerst den Namen des Aktionsteils, wie er in der config.ini unter „ActionParts“ steht, dann eine Tabelle mit Optionen. Diese Optionen legen die Eingabefelder des Aktionsteils im Editor fest. „Hello World“ hat keine Eingaben, deshalb sind alle Optionen im Grunde leer. Übergib aber immer die vollständige Tabelle, damit nichts falsch eingestellt wird. Die einzelnen Optionen sind weiter unten beschrieben.

-- editor.lua

registerActionPart('Print Hello World', {
	isif = false,
	link1 = { text = '', use = false, control = 0 },
	link2 = { text = '', use = false, control = 0 },
	integers = { use = 0, useint3 = false, pointlabel = '', pointdialog = 0 },
	integer1 = { text = '', control = 0, min = 0, max = 0, val = 0, options = {} },
	integer2 = { text = '', control = 0, min = 0, max = 0, val = 0, options = {} },
	integer3 = { text = '', control = 0, min = 0, max = 0, val = 0, options = {} },
	path = { text = '', use = false, filter = 0 },
	string = { text = '', use = 0 },
	link1filter = {},
	link2filter = {},
	stringfilter = {}
})

In der Datei player.lua bekommt registerActionPart() ebenfalls zwei Argumente: wieder den Namen des Aktionsteils und dann die Callback-Funktion, die im Spiel läuft, wenn der Aktionsteil ausgeführt wird. Sie erhält zwei Parameter:

• „activeAction“ ist die Aktion, zu der der Aktionsteil gehört,
• „actionPart“ ist der Aktionsteil selbst mit allen Einstellungen, die im Editor gewählt wurden.

Die Funktion muss einen Wahrheitswert zurückgeben, normalerweise false, wenn sie fertig ist. Gibst du true zurück, wiederholt sich der Aktionsteil endlos.

-- player.lua

registerActionPart('Print Hello World', function(activeAction, actionPart)
    print("Hello, World!")
    return false
end
)

Über die Grundlagen hinaus: bewährte Vorgehensweisen

Text des Aktionsteils und Übersetzung

Eigener Aktionsteil

Standardmäßig wird der Name des Aktionsteils nicht nur in der Liste der Aktionsteile im Editor angezeigt, sondern auch in der Liste innerhalb einer Aktion. Du kannst beide Bezeichnungen aber getrennt festlegen und sogar die Eingaben des Nutzers über Parameter in den Text einbauen. Im Bild heißt der Aktionsteil „Log string“, in der Aktion erscheint er aber als „Print '___' to the log“, ergänzt um die Eingabe „Hello, World!“.

Dieser zusätzliche Text entsteht über die Übersetzungsfunktion in editor.lua<

-- editor.lua

registerActionPart('LOG_STRING',{
	isif = false,
	link1 = { text = '', use = false, control = 0 },
	link2 = { text = '', use = false, control = 0 },
	integers = { use = 0, useint3 = false, pointlabel = '', pointdialog = 0 },
	integer1 = { text = '', control = 0, min = 0, max = 0, val = 0, options = {} },
	integer2 = { text = '', control = 0, min = 0, max = 0, val = 0, options = {} },
	integer3 = { text = '', control = 0, min = 0, max = 0, val = 0, options = {} },
	path = { text = '', use = false, filter = 0 },
	string = { text = 'LOG_TEXT', use = 1 },
	link1filter = {},
	link2filter = {},
	stringfilter = {}
})

-- 1 = German translations
translation(1, 'LOG_STRING', 'Text loggen')
translation(1, 'LOG_STRING_Name', "Schreibe '%string' ins Log")
translation(1, 'LOG_TEXT', "Text")

-- 2 = English translations
translation(2, 'LOG_STRING', 'Log string')
translation(2, 'LOG_STRING_Name', "Print '%string' to the log")
translation(2, 'LOG_TEXT', "Text")

# config.ini

ActionParts=LOG_TIME,LOG_STRING

-- player.lua

function print_time_to_log()
    local time = getTime()

    if(time == 0) then
        print("First execution of this action part.")
    else
        print(time .. "ms passed since the last execution of this action part.")
    end
    
    getTime( {flags = 1, reset = true} )
end

function print_string_to_log(text)
    print(text)
end

registerActionPart('LOG_TIME', function(activeAction, actionPart)
    print_time_to_log()
    return false
end
)

registerActionPart('LOG_STRING', function(activeAction, actionPart)
    print_string_to_log(actionPart.String)
    return false
end
)