important Lezione Propedeutica 01032008

Lezione propedeutica.

Facciamo un riassunto delle informazioni minime che dovreste già sapere per poter scriptare. E' una carrellata sulle cose fondamentali:
(il simbolo § indica argomenti avanzati)

1. Gestione degli script

1.1 Come si crea uno script  "New Script"
1.2 Come si edita uno script
1.3 Running/Reset degli script
1.4 Come si debugga uno script
1.5 Impostazione delle permissions

2. Sintassi del linguaggio lsl2

2.1 tipo variabili
2.2 variabili globali e locali
2.3 funzioni
2.4 struttura a stati
2.5 costrutti elementari (for, while, if, jump)

3. Libreria lsl

3.1 funzioni di gestione stringhe
3.2 funzioni di gestione matematica
3.3 funzioni di gestione liste
3.4 funzioni di gestione eventi listen
3.5 funzioni timer
3.6 funzioni touch
3.7 uso di lldialog


1.1 Come si crea uno script

Avete due sistemi:
a) lo create dall'inventory (create new script) e poi lo trascinate nel content (questo è l'unico modo che funziona con opensim).
b) dal content di un oggetto fate "New Script" e vi verrà creato uno script che poi andrete a rinominare

1.2. Come si edita uno script

Cliccate sullo script nell'inventory dell'oggetto (oppure tasto destro/open) vi si apre un "editor" dove potete fare le cose tipiche che si fanno in ambiente word:
* ctrl-c ctrl-v, funzionano
* shift-canc NON funziona, quindi dovete fare invece ctrl-c e poi shift-canc altrimenti perdete il testo precedente.
* ctrl-z funziona
Potete fare ctrl-f per fare ricerca e sostituzioni. Ricordatevi di mettere "case insensitive".

Syntax Highlighting ed help.
* Le funzioni speciali del linguaggio sono rappresentate in "rosso". se ci passate sopra con il mouse avete un aiuto sulla sintassi (moolto utile).
* in verde e blu i "verbi" del linguaggio. anche qui si passa sopra per info

Quando salvate lo script vi segnala gli errori e la riga dove andare per correggerli. Se vi sono errori lo script viene salvato lo stesso ma NON è running (non fa niente!!).

1.3 Running reset degli script.

Potete in ogni momento sospendere uno script cliccando sul box di "Running" e rimetterlo running successivamente. Utile per stoppare uno script che sta dando di testa.

Analogamente per il reset. Il reset fa ripartire lo script da zero, PERDENDO tutti i dati che stava usando. Utile per correggere uno script che ha dato stack/collision.

Le stesse operazioni possono essere fatte da Tools->Set Script running/not running in selection oppure Tools->Reset Scripts in selection.

1.4. Come si debugga uno script

Ci sono virtualmente infiniti modi di verificare se uno script sta facendo quello che deve,  visto che la maggior parte del tempo fa cose strane :(

* Mettete scritte di debug. La cosa più semplice è di usare llOwnerSay(str), llSay(0, ""), oppure llSay(10,""). Da preferirsi la terza perchè la potete utilizzare senza disturbare la chat pubblica.

E' facile scriptare un oggetto perchè ascolti sulla porta 10 e ve la rilanci come llOwnerSay.

§ 1.4.1 Debug avanzato
Altri sistemi sono meno semplici da strutturare e di solito non si usano spesso:
* http di log su un sito esterno, (lo vedremo meglio nella lezione su httprequest)
* colorazione di prim (utile per segnalare lo stato di busy)
* llSetText in cima all'oggetto
* Invio di IM

 § Visto che le chat possono essere difficili da consultare, ho preparato un logging su un sito esterno (httplog) che potete usare per i vostri test (si vedrà meglio nella lezione httprequest).

 scrivete il seguente in cima al vostro script:
string sURL="http://www.salahzar.info/lsl/httplog.php?pass=PASS";
debug(string k,string action,string str)
{
    string s=sURL+"&key="+llEscapeURL(k)+"&action="+action+"&text="+llEscapeURL(str);
    llOwnerSay(s);
    llHTTPRequest(s,[],"");
}

1.5 IMPOSTAZIONE DELLE PERMISSIONS

Vi sono svariate tipologie di permissions per gli oggetti:
* COPY (potete avere diverse copie)
* MODIFY (potete modificare le caratteristiche)
* TRANSFER (potete trasferirlo, spesso sinonimo di venderlo ad altri)

Per gli script:
* COPY lo script può essere ricopiato
* MODIFY lo script può essere visto
* TRANSFER venduto

Anche le texture hanno le loro permissions.

Permissions più diffuse:
Un oggetto "FULL-PERMISSIONS" può essere visto, aperto, modificato, trasferito.
"COPY-MODIFY" è vostro lo potete modificare ma non trasferire
"MODIFY-TRANSFER" modificare, trasferire ma non copiare

Per gli script le combinazioni più diffuse sono:
* FULL-PERMISSIONS script "open source"
* COPY (no modify) i più diffusi se volete proteggere la proprietà intellettuale
* NO-PERMISSIONS sconsigliato perchè impedisce anche il copy degli oggetti in cui è contenuto

2 SINTASSI del linguaggio lsl2

2.1 Tipo delle variabili

* integer (numeri, canali, contatori, flag, handle, importi in L$).
§ 32bit con segno. da −2,147,483,648 a +2,147,483,647

* float (contiene valori in virgola mobile). Es. 3.1415 (o PI)
§ 32 bit, circa 10 cifre significative, da 10E-38 a 10E38 circa.

* string (array di "bytes" gestiti normalmente in una sorta di UTF-8, simile all'ascii), dimensione massima normalmente 4000 bytes
§ (che possono essere anche molti meno se utf-8 di lingue strane). Esempio "città" 5 caratteri utf-8, ma 6 bytes.

* key (rappresentano le UUID di oggetti, texture, avatar ecc), sono "stringhe" lunghe 34 bytes esempio 39941cda-47c1-f928-30e0-5cc9ce9632a7

* vector (sono 3 float, rappresenta posizioni, velocità, colori..), esempio <x,y,z>, <r,g,b> dove r,g,b compresi fra 0 e 1 per i colori.

* rotation (sono 4 float), anche rappresentabili con 3 float. esempio <x,y,z,w>

* list. Liste eterogenee di dati. Esempio [ "Alpha", 5, <1,0,0> ]



2.2 variabili globali e locali

All'inizio di un programma si specificano le variabili viste globalmente ovunque. Una variabile globale quando viene modificata in un punto dello script appare modificata ovunque. Le variabili globali vengono allocate in un'area chiamata "statics".

Le variabili globali vanno dichiarate PRIMA della dichiarazione degli stati

Ogni funzione / stato alloca le variabili locali sullo stack. Le variabili locali usate all'interno di una funzione od evento vengono rilasciate al termine dell'evento o della funzione.

E' importante distinguere fra variabili locali e globali. Confonderle può condurre ai seguenti problemi:

* pensi di scrivere su una variabile globale ma invece scrivi su una variabile locale che sparisce
* scrivi su una variabile globale pensando di scrivere su una locale provocando il malfunzionamento di un altro pezzo di programma

Per evitare confusioni, io suggerisco di usare una nomenclatura chiara, prefissando le variabili gloabli con una lettera che indica il loro tipo e mettendole tutte in maiuscolo.

iNOTECARD ad esempio, vPOS, lLISTA....

2.3 funzioni

Le funzioni vanno messe prima degli stati e possono essere mischiate con le dichiarazioni di globals.

Servono a rendere facilmente utilizzabile pezzi di codice che si ripete sempre uguale oppure per rendere "riciclabile" pezzi di codice che avete già fatto in altri oggetti.

E' raccomandabile usare molte funzioni nel vostro codice, anche se a causa della struttura primordiale di questo linguaggio le funzioni possono rallentare e/o aumentare il consumo di memoria.

In particolare ricordate che ogni volta che passate dei parametri ad una funzione, questi parametri vengono ricopiati e quindi occupano uno spazio almeno doppio. In quei casi anche se brutto, è meglio ricorrere alle variabili globali.

Questo vale in particolare se avete bisogno di passare delle liste o delle stringhe molto grosse.


2.4 struttura a stati e code di eventi

Il programma lsl quando entra in esecuzione è sempre in uno stato, come minimo il default state. Tutti gli eventi sono associati a quello stato se cambiate stato le code di eventi VENGONO cancellate!

Per ogni evento c'è una "coda di eventi" per registrare le attività che devono essere eseguite dall'oggetto (task). La coda di eventi è limitata.

§ Notizia curiosa: se siete in una zona noscript il vostro programma NON è in esecuzione, ma le code di eventi continuano ad essere aggiornate (fino al loro limite).

Gli eventi più importanti sono:

- touch_start(integer count)  (da non confondere con touch(integer count)).
- on_rez(integer parm)
- state_entry()
- listen()
- timer()

2.5 costrutti elementari

- for(integer i=0;i<10;i++){}
- do {} while (<test>) ;
- while (<test> ) {}
- if(<test>) {}
- if(<test>) {} else {}
- @label ....... jump label
- chiamata di funzione

3. Libreria lsl

3.1 gestione stringhe

Fondamentali!!!

- x="string"
- llStringLength(x) per ottenere la sua lunghezza  in caratteri (non bytes!)
§ L'occupazione effettiva dipende dall'uso di caratteri UTF-8 estesi.
- llStringTrim(x,STRING_TRIM) per togliere spazi in testa e in coda
- llGetSubString(x,start,end) per ottenere un pezzo di una stringa. Nota l'uso di indici negativi per riferire agli ultimi elementi della stringa. Nota la partenza da 0
- llDeleteSubString(x,start,end) per cancellare pezzi di stringa
- llSubStringIndex(src,pattern) cerca una stringa in un'altra
- llInsertString(dst,pos,src) inserisce una stringa dentro un'altra
§ - llMD5String(str,nonce)  "firma" una stringa per sicurezza
§ - llXorBase64Strings(s1,s2) "cripta" una stringa con una password
§ - llEscapeURL(s) trasforma una stringa in modo che sia utilizzabile su internet
§ - llUnescapeURL(s) ritrasforma una stringa internet in formato normale

Trucco: usate s=(s="")+s+x; invece di s+=x per ridurre l'uso di memoria

3.2 funzioni matematiche

Le più importanti:

- llFrand(maxnum) per la generazione causale di canali, password etc
- llFabs()
- llRound()
§ - llSin/llCos (in radianti) per la costruzione di strutture circolari

Rotazioni, visto che sono fra le più difficili :)

§- llEuler2Rot (converte un vettore euleriano in una rotazione) e llRot2Euler
§- llAxes2Rot (fwd, left, fwd % left) dati due vettori  determina la rotazione implicita


3.3 funzioni di gestione liste

Ricordatevi che le funzioni di liste non modificano MAI la lista ma ritornano sempre nel caso una lista modificata! (Questo aumenta l'uso della memoria)


- llDeleteSubList(src,start,end) toglie un pezzo di lista

- llGetListLength(lst)
- llList2<Type>(lst,index) estrae un elemento tipato
  § attenzione se è un vettore conviene estrarlo in genere con
  (vector)llList2String(lst,index)
- llList2List(src,start,end) estrae una sottolista
- llListFindList(src, lst) cerca un insieme di elementi nella lista
- llListInsertList(dst,src,pos) inserisce una lista
- llListRandomize(lst,stride) mette una lista in ordine casuale
- llListReplaceList(dst,src,start,end)

§ Funzioni avanzate

§- llGetListEntryType(lst,index) tipo dell'elemento della lista
§- llList2ListStrided(src,start,end,stride) estrae una "lista intervallata"
§- llList2CSV(lst) salva una lista in una stringa
§- llDumpList2String(list,separator) salva una lista in una stringa
§- llCSV2List(string) ripristina una lista da una stringa
§- llListSort(src,stride,ascending)
§- llListStatistics
§- llParseString2List(src,sep,spacers)
§- llParseStringKeepNulls(src,sep,spacers)

§ Trucco: usate lst=(lst=[])+lst+x invece di lst+=x per ridurre l'uso di memoria

3.4 Funzioni di gestione eventi listen

integer handle=llListen(channel,name,id,string) => apre l'ascolto su un canale

channel:0  è quello dove gli avatar parlano
channel:>0 ogni avatar può parlare su quel canale facendo /x parlo
§ channel:<0 solo gli oggetti possono parlare su quel canale
§ channel:DEBUG_CHANNEL usato dagli oggetti per segnalare stati strani (script con triangolino giallo)

il canale è usato anche dalla funzione llDialog (che quindi non funziona se parallelamente non è stato fatto un llListen)

NB: se non si fa la llListen, l'oggetto NON gestirà l'evento listen() anche se definito!!
§ NB: i listeners creano lag, specie quelli sul canale 0
§ NB: listener su canali negativi generano MENO lag

§ In generale occorre limitare il numero di listeners al minimo possibile e rimuovere l'handle non appena possibile con la funzione llListenRemove(handle).

Usate sempre dei debug per essere sicuri di cosa state ricevendo e di come avete impostato il listener. Molti oggetti funzionano male perchè:

- non avete impostato il listener
- l'avete impostato male (sul canale sbagliato, specificando un id sbagliato, di solito si imposta NULL_KEY, ma se state facendo un llDialog potete mettere la key di chi vi ha toccato) ecc.
§ - è stato disattivato l'handle con una llListenRemove

§ La id può essere impostata a llGetOwner () in modo che l'oggetto risponda solo all'owner. Per farla rispondere al gruppo basta inserire un test nell'evento:
if(llSameGroup(id)) ....

3.5 funzioni timer

llSetTimerEvent(seconds)    se 0 viene disabilitato

Si usa per moltissimi casi, fra cui:

* fare una cosa ogni tot secondi (es. cambiare foto)
§ * gestire un "timeout" esempio mantenere acceso un listener solo per 30 secondi per ridurre il lag
§ * gestire timer multipli
§ * produrre un evento concordato (llSetTimerEvent(0.1) fa scattare l'evento)

Ricordate che llSetTimerEvent imposta l'evento in modo RIPETUTO, quindi se non lo spegnete l'evento si manifesta di nuovo ogni tot secondi.

3.6 Funzioni di touch

touch_start(integer count)

Sono lo strumento principale per gestire l'interazione con gli avatar (ce ne sono altri, mq il touch è quello che produce la MINORE quantità di lag).

E' importante distinguere fra touch_start e touch. Il primo scatta solo una volta quando l'oggetto viene toccato.
Touch invece continua a scattare per tutto l'intervallo di tempo in cui l'avatar mantiene cliccato il tasto sinistro del mouse.

Cos'è il parametro count? Dice QUANTI avatar stanno toccando l'oggetto. In generale possiamo supporre per semplicità che ce ne sia uno soltanto e per ottenerne l'identità
scriviamo
key avkey=llDetectedKey(0)

§ ma se volessimo essere precisi dovremmo fare:

for(integer i=0;i<count;i++)
{
    key avkey=llDetectedKey(i);
    ...
}



§ Altre interazioni possibili:

* la listen precedentemente citata (ma è considerata spesso scomoda)
* le funzioni di collisione (ma l'avatar deve esplicitamente andare addosso all'oggetto)
* sensor (l'avatar è vicino all'oggetto)



3.7 llDialog

funziona in pieno accordo con il touch: ecco il framework indicativo per usarlo

integer iLISTEN=0;
integer iCHANNEL=-3000;

default
{
touch_start(integer count)
{
    key avkey=llDetectedKey(0);
    list options=[ "o1", "o2", "o3" ];
    iLISTEN=llListen(iCHANNEL,"",avKey,"");
    llSetTimerEvent(60); // deve rispondere entro 60 secondi
    llDialog(avkey, "please say something",options,iCHANNEL);
}
timer()
{
    llRemoveListener(iLISTEN);
    llSay(0,"Timeout please touch me again for talking");
    llSetTimerEvent(0);
}
listen(integer channel, string name, key id, string str)
{
    llSay(0,"you told me "+str);
    llSetTimerEvent(0);
    llRemoveListener(iLISTEN);
}
}