ATOMIC AI SPECIAL EFFECTS AND PARTICLE SYSTEM SPEC

RULE: This document defines the complete and binding system for special effects and particles in the Atomic language.
RULE: All rules defined here are mandatory.
RULE: No effect or particle behavior exists outside this specification.

GENERAL DISTINCTION
RULE: Atomic provides two distinct visual effect systems:
predefined animated special effects
custom particle systems
RULE: These two systems are conceptually and technically separate.
RULE: Predefined animated special effects are simpler and not user-configurable at the particle level.
RULE: Custom particle systems are fully configurable and programmable.

PREDEFINED ANIMATED SPECIAL EFFECTS
RULE: Predefined animated special effects are triggered using a drawing function.
RULE: The function is:
disegna effetto speciale animato predefinito --> (ARGUMENT: value)
RULE: This function does not return any value.
RULE: Predefined special effects are internally implemented using particle systems.
RULE: The internal particle implementation is not exposed to the user.
RULE: The user cannot access, modify, or control individual particles of predefined effects.

SUPPORTED PREDEFINED EFFECT TYPES
RULE: The EFFETTO argument accepts only the following text values:
"nuvola"
"esplosione"
"ellisse"
"anello"
"fumo"
"fumo che sale"
"fuoco d'artificio"
"bagliore"
"pioggia"
"neve"
"scintilla"
"stella"
RULE: No other predefined effect types exist.

PREDEFINED EFFECT ARGUMENTS
RULE: Predefined animated special effects support the following arguments:
EFFETTO
X
Y
COLORE
DIMENSIONE
TRASPARENZA
Z
RULE: DIMENSIONE accepts only the following text values:
"piccolo"
"medio"
"grande"
RULE: Z accepts only the following text values:
"sopra"
"sotto"
RULE: All arguments are optional unless explicitly required.
RULE: Default values are used when arguments are omitted.

CUSTOM PARTICLE SYSTEM
RULE: The custom particle system is independent from predefined special effects.
RULE: The custom particle system allows the creation of personalized visual effects.
RULE: The system is composed of three distinct elements:
- particle profiles
- particle generators
- emission commands

PARTICLE PROFILE
RULE: A particle profile defines the behavior and appearance of particles.
RULE: A particle profile is created using:
ottieni particella --> (ARGUMENT: value)
RULE: This function returns a particle profile.
RULE: The returned value must be stored in a variable.
RULE: A particle profile is not a particle instance.
RULE: Particle profiles have no name and no identity beyond the variable that references them.
RULE: Individual particles are never accessible from user code.

PARTICLE PROFILE ARGUMENTS
RULE: A particle profile may define properties such as:
FORMA
COLORE INIZIALE
COLORE MEDIANO
COLORE FINALE
DIMENSIONE MINIMA
DIMENSIONE MASSIMA
VELOCITA MINIMA
VELOCITA MASSIMA
DIREZIONE MINIMA
DIREZIONE MASSIMA
ROTAZIONE MINIMA
ROTAZIONE MASSIMA
DURATA MINIMA
DURATA MASSIMA
SCALA ASSE X
SCALA ASSE Y
TRASPARENZA INIZIALE
TRASPARENZA MEDIANA
TRASPARENZA FINALE
COLORE INIZIALE
COLORE MEDIANO
COLORE FINALE
CRESCITA
ACCELERAZIONE
DURATA MINIMA
DURATA MASSIMA
VARIAZIONE VELOCITA
VARIAZIONE DIREZIONE
VARIAZIONE ROTAZIONE
INCREMENTO DIREZIONE
COLORE ADDITIVO
RULE: These arguments define ranges or values used at particle creation time.
RULE: The evolution of particles over time is handled internally by the engine.

PARTICLE GENERATOR
RULE: A particle generator defines where and how particles are emitted.
RULE: A particle generator is created using:
ottieni generatore di particelle --> (ARGUMENT: value)
RULE: This function returns a particle generator.
RULE: The returned value must be stored in a variable.
RULE: A particle generator is not visible by itself.

PARTICLE GENERATOR ARGUMENTS
RULE: A particle generator may define properties such as:
X
Y
LARGHEZZA
ALTEZZA
TIPO
DISTRIBUZIONE
RULE: The generator defines the spatial emission area.
RULE: The generator does not control particle behavior after emission.

GENERATOR ACTIVATION
RULE: A particle generator is activated using:
attiva generatore di particelle --> (NOME:) (PARTICELLA:) (NUMERO:)
RULE: This command does not return any value.
RULE: NUMERO specifies how many particles are emitted per activation step.
RULE: The generator may emit particles continuously until stopped or destroyed.
RULE: Particle generators are not elements.
RULE: Particle generators cannot be modified after creation.
RULE: The function "modifica un elemento" applies only to objects and instances.
RULE: Using "modifica un elemento" on particle generators is FORBIDDEN.
RULE: For dynamic particle effects, particles must be drawn directly using
      "disegna direttamente delle particelle".

ONE-SHOT GENERATOR ACTIVATION
RULE: A particle generator may be activated for a single emission using:
attiva generatore di particelle solo per un istante --> (NOME:) (PARTICELLA:) (NUMERO:)
RULE: This emits particles only once.
RULE: No continuous emission occurs.

DIRECT PARTICLE EMISSION
RULE: Particles may be emitted directly without using a generator.
RULE: Direct emission is performed using:
disegna direttamente delle particelle --> (NOME:) (X:) (Y:) (NUMERO:)
RULE: This command uses a particle profile.
RULE: Particles are emitted at the specified position.
RULE: This command is typically used inside CICLO CONTINUO.

EXECUTION MODEL
RULE: The particle system updates autonomously.
RULE: Particle simulation does not require user-written update code.
RULE: Particle behavior continues independently of CICLO CONTINUO.
RULE: CICLO CONTINUO may be used to control when particles are emitted.

DESIGN PRINCIPLES
RULE: The particle system is designed to:
be visually rich
remain simple to use
separate user logic from internal simulation
allow both simple and advanced effects

SPECIAL EFFECTS AND PARTICICLES FUNCTIONS
disegna effetto speciale animato predefinito --> (X:) (Y:) (Z:"sopra"|"sotto") (DIMENSIONE: "piccolo"|"medio"|"grande") (COLORE:) (EFFETTO: "nuvola"|"esplosione"|"ellisse"|"pixel"|"sfera"|"anello"|"fumo"|"fumo che sale"|"fuoco d'artificio"|"bagliore"|"pioggia"|"neve"|"scintilla"|"stella")
disegna effetto speciale su un elemento quando viene creato --> (ELEMENTO:) (EFFETTO: "nuvola"|"esplosione"|"ellisse"|"pixel"|"sfera"|"anello"|"fumo"|"fumo che sale"|"fuoco d'artificio"|"bagliore"|"pioggia"|"neve"|"scintilla"|"stella") (DIMENSIONE:  "piccolo"|"medio"|"grande") (COLORE:) (Z: "sopra"|"sotto")
disegna effetto speciale su un elemento quando viene distrutto --> (ELEMENTO:) (EFFETTO: "nuvola"|"esplosione"|"ellisse"|"pixel"|"sfera"|"anello"|"fumo"|"fumo che sale"|"fuoco d'artificio"|"bagliore"|"pioggia"|"neve"|"scintilla"|"stella") (DIMENSIONE: "piccolo"|"medio"|"grande") (COLORE:) (Z: "sopra"|"sotto")
disegna effetto speciale su un elemento --> (ELEMENTO:) (EFFETTO: "nuvola"|"esplosione"|"ellisse"|"pixel"|"sfera"|"anello"|"fumo"|"fumo che sale"|"fuoco d'artificio"|"bagliore"|"pioggia"|"neve"|"scintilla"|"stella") (DIMENSIONE: "piccolo"|"medio"|"grande") (COLORE:) (Z: "sopra"|"sotto")
nome_variabile = ottieni generatore di particelle --> (X:) (Y:) (ALTEZZA:) (LARGHEZZA:) (FORMA: "rettangolo","ellisse","rombo","linea") (DISTRIBUZIONE: "omogenea","verso il centro","verso il bordo")
nome_variabile = ottieni particella --> (FORMA:"pixel"|"nuovola"|"cerchio"|"disco"|"esplosione"|"bagliore"|"linea"|"anello"|"fumo"|"neve"|"scintilla"|"sfera"|"quadrato"|"stella") (DIMENSIONE MINIMA/MASSIMA:) (DIREZIONE MINIMA/MASSIMA:) (ROTAZIONE MINIMA/MASSIMA:) (VELOCITA MINIMA/MASSIMA:) (SCALA ASSE X/Y:) (TRASPARENZA INIZIALE/MEDIANA/FINALE:) (COLORE INIZIALE/MEDIANO/FINALE:) (CRESCITA:) (ACCELERAZIONE:) (DURATA MASSIMA/MINIMA:) (VARIAZIONE VELOCITA:) (VARIAZIONE DIREZIONE:) (VARIAZIONE ROTAZIONE:) (INCREMENTO ROTAZIONE:) (INCREMENTO DIREZIONE:) (COLORE ADDITIVO: vero|falso)
disegna direttamente delle particelle --> (NOME:) (X:) (Y:) (NUMERO:)	
attiva generatore di particelle solo per un istante --> (NOME:) (PARTICELLA:) (NUMERO:)
attiva generatore di particelle --> (NOME:) (PARTICELLA:) (NUMERO:)

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