The Completes Idiot's Guide to the AL Engine

Hier ist der ideale Ort um über Scripts und Mods für X²: Die Bedrohung zu diskutieren.

Moderators: Moderatoren für Deutsches X-Forum, Scripting / Modding Moderators

Post Reply
ticaki
Posts: 4861
Joined: Wed, 6. Nov 02, 20:31
x3

The Completes Idiot's Guide to the AL Engine

Post by ticaki » Fri, 16. Jul 04, 23:45

Gleich vorweg... Das hier ist nicht für Noobs & Anfänger gedachtet... ;)

---------------------------------------------

Hier mal ne kurze und grobe Beschreibung:

- AL Plugins werden über "init" Skripte mit Namen "!al.plugin.*" oder
"al.plugin.*" ins Spiel eingebunden (Theoretisch liese sich das aber
auch über andere beliebige Skripte erledigen). Diese Skripte werden bei
einem neuen Spiel oder beim Laden eines Savegames ausgeführt.

- Ein AL Plugin wird durch das Command "al plugin: register script"
registriert. Das Plugin wird dabei durch einen Skriptnamen
identifiziert, der Skriptname ist hier also die ID des Plugins.

Code: Select all

001   al engine: register script='al.control.pirat.tl.fill.ph'
002   al engine: register script='al.control.pirat.all.race.m'
003   al engine: register script='al.control.pirat.xenons'
004   al engine: register script='al.control.pirat.all.race.ts'
005   al engine: register script='al.control.pirat.sector.ap'
006   return null
Erstmal das komplette AL-Controlscript

Code: Select all

Script al.control.pirat.sector.ap
Version: 0
for Script Engine Version: 25

Arguments
1: plugin.ID , Var/String , 'plugin ID' 
2: plugin.event , Var/String , 'plugin mode' 

Source Text

001   $plugin.data = get global variable: name=$plugin.ID
002   $maxships = 2
003   if not $plugin.data
004    $plugin.data =  array alloc: size=3
005    set global variable: name=$plugin.ID value=$plugin.data
006    $plugin.data[1] = [TRUE]
007    $temp =  array alloc: size=$maxships
008    $plugin.data[2] = $temp
009   end
010   
011   if $plugin.event == 'init' OR $plugin.event == 'reinit'
012   *$decr = sprintf: pageid=943 textid=1005, null, null, null, null, null
013    al engine: set plugin $plugin.ID description to 'my pirat script'
014    $interval = random value from 100 to 200 - 1
015    al engine: set plugin $plugin.ID timer interval to $interval s
016    return null
017   else if $plugin.event == 'start'
018    $plugin.data[1] = [TRUE]
019   else if $plugin.event == 'stop'
020    $plugin.data[1] = [FALSE]
021   else if $plugin.event == 'isenabled'
022    $on = $plugin.data[1]
023    return $on
024   else if $plugin.event == 'timer'
025 @  = [THIS] -> call script 'al.pirat.sector.ap' :  plugin.data=$plugin.data  maxships=$maxships  Target Sector=LooManckStrats Vermächtnis
026   end
027   return null
- Die AL Engine benutzt Events um mit den Plugins zu kommunizieren: <init> <reinit> <timer> <start> <stop> <isenabled>

Dafür wird einfach das registrierte Plugin-Skript mit Parametern aufgerufen:

<PluginID=PluginScriptName> <event>

Code: Select all

Script al.control.pirat.sector.ap
Version: 0
for Script Engine Version: 25

Arguments
1: plugin.ID , Var/String , 'plugin ID' 
2: plugin.event , Var/String , 'plugin mode' 

- Nach dem Ausführen der al.plugin.* werden die registrierten Plugins
einmal mit folgenden String-Parametern aufgerufen:

<PluginID=PluginScriptName> <init> bei neuem Spiel
<PluginID=PluginScriptName> <reinit> nach Save laden

Code: Select all

011   if $plugin.event == 'init' OR $plugin.event == 'reinit'

- Die AL Engine hält intern nur einen einzigen Statuswert pro Plugin.
Und das ist ein Timerinterval. Falls dieses Interval > 0 ist, wird nach
jedem Ablauf des Intervals das Plugin-Skript mit String-Parametern:

<PluginID=PluginScriptName> <timer>

aufgerufen. Das Timer-Interval kann durch das Command "al plugin: set
timer interval" gesetzt werden.

Code: Select all

014    $interval = random value from 100 to 200 - 1
015    al engine: set plugin $plugin.ID timer interval to $interval s
- Eine Beschreibung des Plugins kann durch "al plugin: set description"
angegeben werden. Erscheint dann im Manage AL Plugin Menü.

Code: Select all

012   *$decr = sprintf: pageid=943 textid=1005, null, null, null, null, null
013    al engine: set plugin $plugin.ID description to 'my pirat script'
- Beschreibung und Timerinterval wird i.d.R im <init> bzw. <reinit>
Event gesetzt.

- Die Events <start> und <stop> werden über das AL Menü ausgelöst.

Code: Select all

017   else if $plugin.event == 'start'
018    $plugin.data[1] = [TRUE]
019   else if $plugin.event == 'stop'
020    $plugin.data[1] = [FALSE]
Dort wird auch der <isenabled> Event benutzt, um festzustellen, ob das Plugin
gestoppt oder gestartet ist. Der <isenabled> Event muß TRUE (gestartet)
oder FALSE zurückgeben.

Code: Select all

021   else if $plugin.event == 'isenabled'
022    $on = $plugin.data[1]
023    return $on
- Der Rest ist durch das Plugin selbst zu erledigen. I.d.R. wird es so
sein, das pro Plugin eine globale Variable existiert, in der die
Statusinfos über ein Array gespeichert sind. Dieses Array kann z.b. so
aufgebaut sein:

0: Datenstruktur-Versionsinformation
1: Plugin State (enabled/disabled)
2: zusätzliche State Daten....
3: ...

Genaueres könnt ihr euch mal in den beigefügten AL Scripts ankucken.

Dadurch das die AL Engine nun das looping fürs Plugin übernimmt, kann
fast problemlos das Plugin "gepatcht" werden. Denn bei jedem neuen
TimerEvent wird die aktuellste Scriptversion verwendet. Das Plugin muß
dann natürlich sicherstellen, das es mit noch alten State-Daten umgehen
kann bzw. muß diese Updaten. Dafür kann man z.b. so eine
Datenstruktur-Versionsinformation im State-Array verwenden.



Ein normaler AL Plugin Arbeitsablauf sieht dann so aus:

1. AL Engine: al.plugin.test

2. al.plugin.test: register script=al.test

3. AL Engine: sende Event <init> (also rufe Skript al.test auf mit
Parametern: "al.test" "init"

4. al.test: Reaktion auf "init": setze Timerinterval und Beschreibung,
initialisiere State-Array und in globaler Variable (Name = PluginID =
PluginScriptName) festhalten.

5. AL Engine: wartet bis gesetztes Timerinterval abgelaufen ist und
sendet dann den Event <timer>.

6. al.test: erkennt <timer> Event und tut irgendwas

7. al erkennt nicht, ob das script ausgeführt werden darf ;)
Ein Beispiel zum besseren Verständnis

Code: Select all

$plugin.enable = $plugin.data[1]
skip if $plugin.enable
  goto end // return null tue nix
8. weiter mit 5)


BalaGi, Kingdoms End, 28.03.2004
Bissle code eingefügt von ticaki ;)

Ein weiteres Beispiel von AJ:
Dieses AL-Plugin sorgt einfach dafür, dass alle 30-45min (Zeile 17 & 18 vom Mainscript) ein Khaak-Schiff im Sektor des Spielers erscheint. Es ist extra einfach gehalten da es hier nur als Beispiel dienen soll.

al.plugin.khaak -> init-Script
al.khaak.main -> AL-Controll-Script
al.khaak.event.timer -> Khaakspawn-Script (das Script welches bei jedem durchlauf gestartet wird)

Script "al.plugin.khaak"

Code: Select all

001   * Register the Script as AL-Plugin
002   al engine: register script='al.khaak.main'
003   return null
Script "al.khaak.main"

Code: Select all

Arguments
1: plugin.ID , Var/String , 'plugin ID' 
2: plugin.Event , Value , 'plugin event' 

001   $plugin.Vars = get global variable: name=$plugin.ID
002   
003   if not $plugin.Vars
004   * Define the Data-Array
005    $plugin.Vars =  array alloc: size=2
006    set global variable: name=$plugin.ID value=$plugin.Vars
007   *  Plugin Version
008    $plugin.Vars[0] = 0
009   *  Plugin Status
010    $plugin.Vars[1] = [TRUE]
011   end
012   
013   if $plugin.Event == 'init' OR $plugin.Event == 'reinit'
014   * If game is started or loaded
015    $description = 'Extra Khaakspawn'
016    al engine: set plugin $plugin.ID description to $description
017    $interval = random value from 1800 to 2700 - 1
018    al engine: set plugin $plugin.ID timer interval to $interval s
019    
020   else if $plugin.Event == 'isenabled'
021   * Return Pluginstatus
022    $enabled = $plugin.Vars[1]
023    return $enabled
024    
025   else if $plugin.Event == 'start'
026   * Set Status to TRUE (enabled)
027    $plugin.Vars[1] = [TRUE]
028    
029   else if $plugin.Event == 'stop'
030   * Set Status to FALSE (disabled)
031    $plugin.Vars[1] = [FALSE]
032    
033   else if $plugin.Event == 'timer'
034   * Start the Script every time the timer is released
035 @  = [THIS] -> call script 'al.khaak.event.timer' :  plugin ID=$plugin.ID  plugin data=$plugin.Vars
036   end
037   
038   return null
Script "al.khaak.event.timer"

Code: Select all

Arguments
1: plugin.ID , Var/String , 'plugin ID' 
2: plugin.Vars , Value , 'plugin data' 

001   $plugin.enabled = $plugin.Vars[1]
002   
003   * If plugin is disabled goto label Exit
004   skip if $plugin.enabled
005    goto label Exit
006   
007   $sector = [PLAYERSHIP] -> get sector
008   $Ship.ObjClass = [PLAYERSHIP] -> get object class
009   
010   if $Ship.ObjClass == Heavy Fighter M3
011   * Khaak M4
012    $khaak.type = Unbekanntes Feindschiff
013    
014   else if $Ship.ObjClass == Cruiser M6
015   * Small KhaakCluster
016    $khaak.type = Unbekanntes Feindschiff
017    
018   else if $Ship.ObjClass == Destroyer M2 OR $Ship.ObjClass == Battle Ship M1
019   * Big KhaakCluster
020    $khaak.type = Unbekanntes Feindschiff
021   end
022   
023   $pos.x = random value from -30000 to 30001 - 1
024   $pos.y = random value from -30000 to 30001 - 1
025   $pos.z = random value from -30000 to 30001 - 1
026   
027   $khaak =  create ship: type=$khaak.type owner=Khaak addto=$sector x=$pos.x y=$pos.y z=$pos.z
028   $khaak -> add default items to ship
029   
030   Exit:
031   return null
Last edited by ticaki on Sun, 18. Jul 04, 22:53, edited 4 times in total.
Zur Zeit nicht aktiv

ticaki
Posts: 4861
Joined: Wed, 6. Nov 02, 20:31
x3

Post by ticaki » Sun, 18. Jul 04, 12:39

Ich hab den Off-Topic mal abgespaltet!
Das findet man jetzt hier: Wie bekomme ich die Std AL-Scripts ans laufen

Dieser Topic richtet sich ausschließlich an fortgeschrittene Scripter. ;)

Gruß ticaki
Zur Zeit nicht aktiv

Post Reply

Return to “X²: Die Bedrohung - Scripts und Modding”