ATOMIC AI OBJECTS SPEC (EN)

SCOPE
RULE: This document defines the complete and binding object system of the Atomic language.
RULE: All rules defined here are mandatory.
RULE: No object-related behavior exists outside this specification.

TERMINOLOGY
RULE: Atomic uses the following terms:
RULE: object
An abstract definition of structure and behavior.
RULE: instance
A concrete realization of an object.
RULE: element
A generic term referring to either an object or an instance.
RULE: These terms are semantic and not interchangeable.

OBJECT CREATION
RULE: An object is created using the function:
crea un oggetto --> (NOME:) (other arguments)
RULE: An object:
defines structure and behavior
may have an image
may define default arguments
does not represent a single visible entity
RULE: Objects are abstract and are not rendered.

INSTANCE CREATION
RULE: An instance is created using the function:
crea un esemplare --> (OGGETTO:) (other arguments)
RULE: An instance:
inherits structure and behavior from its object
overrides object arguments with instance arguments
may have a name
requires a name only if referenced externally

OBJECT AND INSTANCE CREATION ARGUMENTS
RULE: Objects and instances share the same set of supported arguments at creation time.
RULE: The following arguments are supported when creating an object or an instance:
NOME
OGGETTO
X
Y
Z
SCALA ASSE X
SCALA ASSE Y
IMMAGINE
TRASPARENZA
COLORE
VELOCITA
DIREZIONE
ROTAZIONE
DURATA
RULE: Arguments may be omitted.
RULE: Omitted arguments assume their default values.
RULE: Arguments are optional unless explicitly required by context.
RULE: Argument names are case-sensitive.
RULE: Predefined argument names must be written in uppercase.

CREATION LOCATION
RULE: Objects and instances are normally created inside INIZIA.
RULE: Instances may be created inside CICLO CONTINUO only if creation is conditional.
RULE: Unconditional instance creation inside CICLO CONTINUO creates a new instance every frame.
RULE: This behavior is intentional.

OBJECT CONTEXT EXECUTION
RULE: Code may be executed from the perspective of an object using:
<object name> esegue al suo interno questo codice
{
code
}
RULE: This code is executed:
by every instance of the object
once per frame if inside CICLO CONTINUO
RULE: Context execution does not create new instances.
IMPLICIT LOCAL VARIABLES
RULE: Inside object context execution:
instance arguments behave as implicit local variables
RULE: Modifying these variables directly modifies the instance state.
RULE: No prefix or accessor is required inside the object context.

EXTERNAL MODIFICATION OF ELEMENTS
RULE: Atomic provides a dedicated function to modify an element externally:
modifica un elemento --> (NOME:) (arguments)
RULE: Supported arguments are:
X
Y
Z
SCALA ASSE X
SCALA ASSE Y
IMMAGINE
TRASPARENZA
COLORE
VELOCITA
DIREZIONE
ROTAZIONE
RULE: One or more arguments may be specified.
RULE: Unspecified arguments are not modified.
RULE: This function does not create instances.
RULE: This function returns no value.

PREDEFINED VARIABLE SE STESSO
RULE: Inside object context execution, the predefined variable:
sé stesso
exists.

RULE: sé stesso:
refers to the instance currently executing the code
is usable only inside object context execution
allows operations on the current instance without using its name

INSTANCE DESTRUCTION
RULE: An instance may be destroyed explicitly using:
distruggi un esemplare --> (ESEMPLARE:)
RULE: All instances of an object may be destroyed using:
distruggi tutti gli esemplari di --> (OGGETTO:)
RULE: Destruction removes the instance from logic and rendering

IMPLICIT INSTANCE DESTRUCTION (DURATA)
RULE: An instance may be destroyed implicitly using the argument:
DURATA
RULE: DURATA defines the lifetime of an instance.
RULE: DURATA is a numeric value.
RULE: DURATA represents a duration measured in frames.
RULE: When DURATA reaches zero:
the instance is automatically destroyed
destruction is immediate
no further code is executed for that instance
RULE: DURATA decreases automatically over time.
RULE: DURATA may be assigned:
at instance creation
via modification of the instance
RULE: Explicit destruction and implicit destruction via DURATA are both valid.
RULE: If both mechanisms are present, the first one triggered destroys the instance.


INSTANCE SELECTION AND QUERY
RULE: Atomic provides functions to locate instances without manual iteration.
RULE: The following functions exist:
ottieni risultato controllo se esistono esemplari di --> (OGGETTO:)
ottieni nome dell'esemplare più vicino a --> (X:) (Y:) (OGGETTO:)
ottieni nome dell'esemplare più lontano da --> (X:) (Y:) (OGGETTO:)
RULE: These functions:
return instance names
do not modify instance state
support group-based logic

SPATIAL INTERACTION FUNCTIONS
RULE: Atomic provides spatial interaction functions.
RULE: The following functions exist:
ottieni distanza tra due elementi --> (ELEMENTO 1:) (ELEMENTO 2:)
ottieni risultato controllo collisione tra --> (ELEMENTO 1:) (ELEMENTO 2:)
RULE: These functions:
return values
do not modify element state

INSTANCE VISIBILITY
RULE: An instance is visible only if it has an IMMAGINE assigned.
RULE: If an instance has no image:
it exists logically
its code is executed
nothing is rendered
RULE: Invisible instances may be used as logic controllers.

AUTOMATIC MOVEMENT
RULE: If an instance has a VELOCITA value:
its position is updated automatically by the engine
movement follows the DIREZIONE
RULE: Manual modification of X or Y is not required for movement.

AUTOMATIC TRANSPORT
RULE: Atomic provides automatic transport:
trasporta elemento al lato opposto quando esce dalla finestra --> (ELEMENTO:)

RULE: This function:
monitors window boundaries
teleports the element to the opposite side

CASE SENSITIVITY AND CONVENTIONS
RULE: Atomic is case-sensitive.
RULE: Predefined arguments:
have fixed names
must be written using correct uppercase
do not work if written in lowercase
RULE: Custom variables and arguments:
may use any naming
conventionally written in lowercase

INHERITANCE MODEL
RULE: Atomic supports simple inheritance.
RULE: An object may serve as a base for multiple instances.
RULE: Inheritance:
is single-object
applies to structure and behavior only
RULE: Object code is executed by all instances.
RULE: Code duplication is not required.

EXTERNAL ACCESS TO INSTANCE VARIABLES
RULE: To access an instance variable externally, Atomic uses the construct:
<variable> del <instance name>
RULE: Supported grammatical variants are:
del
dello
della
dell'
RULE: All variants are semantically equivalent.
RULE: The construct is required only outside object context execution.
RULE: Inside object context execution, instance variables are directly accessible.

UNSUPPORTED OBJECT FEATURES
FORBIDDEN:
object methods
dot notation
multiple inheritance
implicit destruction
special constructors
per-object event systems separate from the frame model

OBJECTS FUNCTIONS
crea un oggetto --> (NOME:) (GENITORE:) (X:) (Y:) (Z:) (SCALA ASSE X:) (SCALA ASSE Y:) (IMMAGINE:) (TRASPARENZA:) (COLORE:) (VELOCITA:) (DIREZIONE:) (ROTAZIONE:)
crea un esemplare --> (NOME:) (OGGETTO:) (X:) (Y:) (Z:) (SCALA ASSE X:) (SCALA ASSE Y:) (IMMAGINE:) (TRASPARENZA:) (COLORE:) (VELOCITA:) (DIREZIONE:) (ROTAZIONE:)
modifica un elemento --> (NOME:) (X:) (Y:) (Z:) (SCALA ASSE X:) (SCALA ASSE Y:) (IMMAGINE:) (TRASPARENZA:) (COLORE:) (VELOCITA:) (DIREZIONE:) (ROTAZIONE:)
trasporta elemento al lato opposto quando esce dalla finestra --> (ELEMENTO:)
distruggi un esemplare -->  (ESEMPLARE:)
distruggi tutti gli esemplari di --> (OGGETTO:)
distruggi questi elementi quando collidono tra loro --> (ELEMENTO 1:) (ELEMENTO 2:) 
nome_variabile = ottieni risultato controllo collisione tra --> (ELEMENTO 1:) (ELEMENTO 2:)
timbra con questo elemento --> (ELEMENTO:)
cancella timbri
fai parlare un elemento --> (NOME: ) (DICE:)
fai pensare un elemento --> (NOME: ) (PENSA:)
imposta elemento trascinabile --> (ELEMENTO: ) (VALORE:)
distruggi elemento quando questa sua variabile locale equivale a --> (ELEMENTO:) (VARIABILE:) (VALORE:)
distruggi elemento quando collide con --> (ELEMENTO:) (ELEMENTO COINVOLTO:)
distruggi elementi che si trovano in quest'area rettangolare --> (ELEMENTO:) (X:) (Y:) (BASE:) (ALTEZZA:)
distruggi elementi che si trovano in quest'area circolare --> (ELEMENTO:) (X:) (Y:) (RAGGIO:)
distruggi elemento quando esce dalla finestra --> (ELEMENTO:)
muovi un elemento verso un punto --> (ELEMENTO:) (X:) (Y:) (VELOCITA:)
nome_variabile = ottieni nome dell'esemplare più vicino a --> (X:) (Y:) (OGGETTO:)
nome_variabile = ottieni nome dell'esemplare più lontano da --> (X:) (Y:) (OGGETTO:)
nome_variabile = ottieni risultato controllo se esistono esemplari di --> (OGGETTO:)
nome_variabile = ottieni risultato controllo se elemento è stato cliccato --> (ELEMENTO:) (TASTO:)
nome_variabile = ottieni risultato controllo se elemento è cliccato --> (ELEMENTO:)  (TASTO:)
nome_variabile = ottieni risultato controllo se elemento ha toccato il bordo della finestra --> (ELEMENTO:)
nome_variabile = ottieni risultato controllo se ci sono elementi in questo punto --> (X:) (Y:)
nome_variabile = ottieni distanza tra due elementi --> (ELEMENTO 1:) (ELEMENTO 2:)
nome_variabile = ottieni ultimo esemplare cliccato

OBJECT MOTION PATH PLANNING FUNCTION
assegna un percorso da seguire a un elemento --> (ELEMENTO:) (PERCORSO:) (VELOCITA:) (RELATIVO:) (QUANDO FINISCE:) (DISEGNA PERCORSO:)
ferma movimento di un elemento --> (ELEMENTO:)
nome_variabile = ottieni un percorso --> (TIPO:) (CHIUSO:) (COORDINATE: x,y / x,y / …,… )
nome_variabile = ottieni velocità percorrenza percorso --> (ELEMENTO:)
imposta velocità percorrenza percorso --> (ELEMENTO:) (VELOCITA:)

FORMAL CLOSURE
RULE: The object system of Atomic is limited to what is defined in this document.
RULE: Any undocumented object behavior:
is invalid
is not part of the Atomic language