Documentation

src/main/generated-sources/sarl/io/sarl/demos/fireworks/Firework.java

@@ -9,6 +9,9 @@ import io.sarl.lang.annotation.SarlSpecification;
 import io.sarl.lang.annotation.SyntheticMember;
 import org.eclipse.xtext.xbase.lib.Exceptions;
 
+/**
+ * Launch janus Kernel and main sarl agent
+ */
 @SarlSpecification("0.5")
 @SarlElementType(8)
 @SuppressWarnings("all")

src/main/sarl/io/sarl/demos/fireworks/Fireworks.sarl

@@ -6,6 +6,9 @@ import io.sarl.demos.fireworks.gui.FXMLViewerController
 
 import static io.janusproject.Boot.*
 
+/*
+ * Launch janus Kernel and main sarl agent
+ */
 class Firework {
 	static def main(controller : FXMLViewerController) {
 		Boot::offline = true

src/main/sarl/io/sarl/demos/fireworks/FireworksFXApplication.sarl

@@ -10,6 +10,9 @@ import javafx.scene.Parent
 import javafx.scene.Scene
 import javafx.stage.Stage
 
+/*
+ * Fireworks demo application
+ */
 class FireworksFXApplication extends Application {
 
 	private var loader : FXMLLoader

src/main/sarl/io/sarl/demos/fireworks/Positions.sarl

@@ -7,6 +7,9 @@ import java.util.UUID
 import java.util.Vector
 import javafx.scene.paint.Color
 
+/*
+ * Data structure used to represent a rocket position
+ */
 class RocketsPos {
 	public val ROCKETREFRESHDELAY = 100
 	
@@ -39,6 +42,9 @@ class RocketsPos {
 	}
 }
 
+/*
+ * Data structure used to represent a fire position
+ */
 class FirePos {
 	public val FIREREFRESHDELAY = 100
 	var positions : List<Vector<Double>>
@@ -61,6 +67,10 @@ class FirePos {
 	}
 }
 
+/*
+ * Data structure referencing every position of every fire and rocket existing
+ * This object is read by the GUI for display
+ */
 class Positions {
 	var rockets = new HashMap<UUID, RocketsPos>()
 	var fire = new HashMap<UUID, FirePos>()

src/main/sarl/io/sarl/demos/fireworks/agents/Fire.sarl

@@ -19,6 +19,9 @@ import java.util.List
 import java.util.UUID
 import java.util.Vector
 
+/*
+ * Fire agent moving with a nice trajectory
+ */
 agent Fire {
 	uses Lifecycle, Logging, Behaviors, DefaultContextInteractions, Schedules
 
@@ -38,8 +41,10 @@ agent Fire {
 	var move : AgentTask
 	var parentAgent : UUID
 	var gravity: Double
-	var mass : Double
 
+	/*
+	 * Freeze itself
+	 */
 	on Freeze {
 		this.frozen = occurrence.value
 		if (frozen)
@@ -48,6 +53,9 @@ agent Fire {
 			wake(new UpdateFirePosition)
 	}
 
+	/*
+	 * Initialization step
+	 */
 	on Initialize {
 		x = new ArrayList()
 		y = new ArrayList()
@@ -68,9 +76,11 @@ agent Fire {
 		vx = xf * 20.0
 		vy = yf * 30.0
 		
-		mass = 10.0
 	}
 
+	/*
+	 * Trigger fixed delay for waking UpdateFirePosition
+	 */
 	on FireReady {
 		move = atFixedDelay(Configuration.FireLifeCycleSchedulingRate) [
 			try {
@@ -81,11 +91,14 @@ agent Fire {
 		]
 	}
 
+	/*
+	 * Update position every time it's triggered by itself
+	 */
 	on UpdateFirePosition [isFromMe(occurrence) && !frozen && !destroyed] {
 		var newx : Double
 		var newy : Double
 		
-		vy = vy - gravity * mass * Configuration.FireLifeCycleSchedulingRate / 100.0
+		vy = vy - gravity * Configuration.FireLifeCycleSchedulingRate / 10.0
 		
 		newx = x.last + vx * Configuration.FireLifeCycleSchedulingRate / 1000.0
 		newy = y.last + vy * Configuration.FireLifeCycleSchedulingRate / 1000.0
@@ -121,12 +134,18 @@ agent Fire {
 		}
 	}
 
+	/*
+	 * Clean every task
+	 */
 	def cleanBeforeExit() {
 		move.cancel(true)
 		exited = true
 		destroyed = true
 	}
 
+	/*
+	 * Kill itself when Exit signal invoked from parent
+	 */
 	on Exit [!exited && isFrom(getParentID)] {
 		frozen = true
 		this.cleanBeforeExit

src/main/sarl/io/sarl/demos/fireworks/agents/LaunchingArea.sarl

@@ -18,6 +18,9 @@ import io.sarl.util.OpenEventSpaceSpecification
 import java.util.Random
 import java.util.UUID
 
+/*
+ * The main agent able to communicate with the GUI
+ */
 agent LaunchingArea {
 	uses DefaultContextInteractions, Lifecycle, Behaviors, Logging, InnerContextAccess
 
@@ -28,6 +31,9 @@ agent LaunchingArea {
 	var maxWidth = 10.0
 	var exited = false
 
+	/*
+	 * Configure according to GUI settings
+	 */
 	on SetupSettings {
 		this.rocketsQuantity = occurrence.rocketsQuantity
 		this.fireQuantity = occurrence.fireQuatity
@@ -35,15 +41,24 @@ agent LaunchingArea {
 		this.maxWidth = occurrence.maxWidth
 	}
 
+	/*
+	 * Kill itself on Exit signal after all inner agent are killed
+	 */
 	on Exit [!hasMemberAgent] {
 		killMe
 	}
 
+	/*
+	 * Transmit Exit signal to all inner agent
+	 */
 	on Exit [hasMemberAgent && !exited] {
 		exited = true
 		innerContext.defaultSpace.emit(new Exit)
 	}
 
+	/*
+	 * Initialization step without GUI
+	 */
 	on Initialize [occurrence.parameters.empty] {
 		rocketsQuantity = 20
 		fireQuantity = 30
@@ -53,6 +68,9 @@ agent LaunchingArea {
 
 	}
 
+	/*
+	 * Initialization step with GUI
+	 */
 	on Initialize [!occurrence.parameters.empty] {
 		var ctrl = occurrence.parameters.get(0) as FXMLViewerController
 		var ispace = defaultContext.createSpace(OpenEventSpaceSpecification, UUID.randomUUID)
@@ -65,6 +83,9 @@ agent LaunchingArea {
 
 	}
 
+	/*
+	 * Create and configure every RocketLauncher
+	 */
 	on CreateArea {
 		var x : Double
 		var i = 0
@@ -76,10 +97,16 @@ agent LaunchingArea {
 		}
 	}
 
+	/*
+	 * Transmit Freeze signal
+	 */
 	on Freeze [!isFromMe(occurrence)] {
 		innerContext.defaultSpace.emit(occurrence)
 	}
 
+	/*
+	 * Start all RocketLauncher when everything is ready
+	 */
 	on MemberJoined [occurrence.inInnerDefaultSpace && memberAgentCount == rocketsQuantity] {
 		info("Area is Ready: All rockets are here")
 		innerContext.defaultSpace.emit(new Launch)

src/main/sarl/io/sarl/demos/fireworks/agents/Rocket.sarl

@@ -21,6 +21,9 @@ import java.util.Random
 import java.util.UUID
 import java.util.Vector
 
+/*
+ * A Rocket that contains fire particles
+ */
 agent Rocket {
 
 	uses Lifecycle, Logging, Schedules, Behaviors, DefaultContextInteractions, InnerContextAccess
@@ -39,11 +42,17 @@ agent Rocket {
 	var id : UUID
 	var move : AgentTask
 
+	/*
+	 * Kill itself after an Exit signal
+	 */
 	on Exit [!hasMemberAgent] {
 		emit(new Exit)
 		killMe
 	}
 
+	/*
+	 * Transmit an Exit signal to inner context
+	 */
 	on Exit [hasMemberAgent && !exited] {
 		exploded = true
 		frozen = true
@@ -53,6 +62,9 @@ agent Rocket {
 		innerContext.defaultSpace.emit(new Exit)
 	}
 
+	/*
+	 * Freeze itself
+	 */
 	on Freeze {
 		this.frozen = occurrence.value
 		if (frozen)
@@ -61,6 +73,9 @@ agent Rocket {
 			wake(new UpdateRocketPosition)
 	}
 
+	/*
+	 * Initialization step
+	 */
 	on Initialize {
 		info("New rocket launched")
 		var rnd = new Random()
@@ -78,6 +93,7 @@ agent Rocket {
 		lifetime = rnd.nextInt(5) * 300 + 300
 		id = UUID.randomUUID
 
+		// Create a background task to update its own position
 		move = atFixedDelay(Configuration.RocketLifeCycleSchedulingRate) [
 			try {
 				wake(new UpdateRocketPosition);
@@ -87,6 +103,9 @@ agent Rocket {
 		]
 	}
 
+	/*
+	 * Update its position at every UpdateRocketPosition event from itself
+	 */
 	on UpdateRocketPosition [isFromMe(occurrence) && !frozen && !exploded] {
 		var vect = new Vector(2)
 		x = x + speedx
@@ -105,6 +124,9 @@ agent Rocket {
 		}
 	}
 
+	/*
+	 * Explode and generate fire
+	 */
 	on Explode {
 		for (var i = 0; i < fireQuantity; i++) {
 			spawnInContext(Fire, innerContext, x, y, grid, id, gravity)
@@ -112,6 +134,9 @@ agent Rocket {
 		// emit(new Launch)
 	}
 
+	/*
+	 * Kill itself when all its inner agents are killed
+	 */
 	on MemberLeft [!isFromMe(occurrence) && !frozen && !hasMemberAgent] {
 		exited = true
 		grid.removeRocketPosition(id)
@@ -119,6 +144,9 @@ agent Rocket {
 		killMe
 	}
 
+	/*
+	 * Emit a FireReady signal when all fire are created
+	 */
 	on MemberJoined [!isFromMe(occurrence) && hasMemberAgent && memberAgentCount == fireQuantity] {
 		innerContext.defaultSpace.emit(new FireReady)
 	}

src/main/sarl/io/sarl/demos/fireworks/agents/RocketLauncher.sarl

@@ -13,6 +13,9 @@ import io.sarl.demos.fireworks.events.Freeze
 import io.sarl.demos.fireworks.events.Launch
 import io.sarl.demos.fireworks.events.RocketReady
 
+/*
+ * A rocket launcher that own a rocket in it's inner context
+ */
 agent RocketLauncher {
 
 	uses Logging, Behaviors, DefaultContextInteractions, InnerContextAccess, Lifecycle
@@ -24,16 +27,25 @@ agent RocketLauncher {
 	var grid : Positions
 	var exited = false
 
+	/*
+	 * Kill itself after an Exit signal
+	 */
 	on Exit [!hasMemberAgent] {
 		emit(new Exit)
 		killMe
 	}
 
+	/*
+	 * Transmit an Exit signal to inner context
+	 */
 	on Exit [hasMemberAgent && !exited] {
 		exited = true
 		innerContext.defaultSpace.emit(new Exit)
 	}
 
+	/*
+	 * Initialization step invoked with parameters
+	 */
 	on Initialize [!occurrence.parameters.empty] {
 		x = occurrence.parameters.get(0) as Double
 		y = occurrence.parameters.get(1) as Double
@@ -44,6 +56,9 @@ agent RocketLauncher {
 		info("New rocket launcher created")
 	}
 
+	/*
+	 * Initialization step by default
+	 */
 	on Initialize [occurrence.parameters.empty] {
 		x = 0.0
 		y = 0.0
@@ -55,16 +70,25 @@ agent RocketLauncher {
 		emit(new RocketReady)
 	}
 
+	/*
+	 * Launch a new rocket after a Launch signal
+	 */
 	on Launch {
 		var vx = Math.random() * 2.0
 		var vy = Math.random() * 5.5 + 2.0
 		spawnInContext(Rocket, getInnerContext, x, y, vx, vy, gravity, fireQuantity, grid)
 	}
 
+	/*
+	 * Transmit a Freeze signal
+	 */
 	on Freeze [!isFromMe(occurrence)] {
 		innerContext.defaultSpace.emit(occurrence)
 	}
 
+	/*
+	 * Launch a new rocket when the previous is destroyed
+	 */
 	on MemberLeft [!isFromMe(occurrence) && !exited] {
 		wake(new Launch)
 	}

src/main/sarl/io/sarl/demos/fireworks/events/events.sarl

@@ -1,27 +1,63 @@
 package io.sarl.demos.fireworks.events
 
+/*
+ * Trigger the launching area for starting the demo
+ */
 event Launch
 
+/*
+ * Setup the Area
+ */
 event CreateArea
 
+/*
+ * Make a rocket explode
+ */
 event Explode
 
+/*
+ * Ask a rocket to kill itself
+ */
 event KillRocket
 
+/*
+ * Ask a fire to kill itself
+ */
 event KillFire
 
+/*
+ * Say that a rocket is ready
+ */
 event RocketReady
 
+/*
+ * Trigger a rocket to update it's position
+ */
 event UpdateRocketPosition
 
+/*
+ * Trigger a fire to update it's position
+ */
 event UpdateFirePosition
 
+/*
+ * Say that a fire is ready
+ */
 event FireReady
 
+/*
+ * Makes a fire spray everywhere
+ */
 event SprayFire
 
+/*
+ * Triggered when the app need to be exited
+ */
 event Exit
 
+/*
+ * Carry all setup informations, send by the GUI
+ */
 event SetupSettings {
 	var rocketsQuantity : Integer
 	var fireQuatity : Integer
@@ -36,6 +72,9 @@ event SetupSettings {
 	}
 }
 
+/*
+ * Freeze signal send by the GUI
+ */
 event Freeze {
 	var value : boolean
 

src/main/sarl/io/sarl/demos/fireworks/gui/FXMLViewerController.sarl

@@ -50,28 +50,46 @@ class FXMLViewerController implements EventListener {
 	@FXML
 	private var stop_button : Button;
 
+	/*
+	 * Emit a kill signal wen the app is exited
+	 */
 	public def cleanExit() {
 		if (this.ispace !== null)
 			this.ispace.emit(new Exit());
 	}
 
+	/*
+	 * Method invoked by the sarl agent to register the object on a space
+	 */
 	public def setGUISpace(ispace : OpenEventSpace) {
 		this.ispace = ispace;
 		this.ispace.register(this);
 	}
 
+	/*
+	 * Get gravity
+	 */
 	public def getGravity() : double {
 		return gravity_input.getValue();
 	}
 
+	/*
+	 * Get Rocket Quantity
+	 */
 	public def getRocketQuantity() : int {
 		return rocket_quantity_input.getValue() as int;
 	}
 
+	/*
+	 * Get Fire Quantity
+	 */
 	public def getFireQuantity() : int {
 		return fire_quantity_input.getValue() as int;
 	}
 
+	/*
+	 * Draw every positions on main canvas
+	 */
 	public def listenAndDraw(grid : Positions) {
 		var gc : GraphicsContext = draw_zone.getGraphicsContext2D();
 		var wait : PauseTransition = new PauseTransition(Duration.seconds(0.03));
@@ -100,12 +118,18 @@ class FXMLViewerController implements EventListener {
 		wait.play();
 	}
 
+	/*
+	 * Catch exit event
+	 */
 	@FXML
 	public def exitApplication(ievent : ActionEvent) {
 		ispace.emit(new Exit());
 		Platform.exit();
 	}
 
+	/*
+	 * Create main sarl agent and do setup
+	 */
 	@FXML protected def actionSetup() {
 		var ievent : SetupSettings = new SetupSettings(this.getRocketQuantity(), this.getFireQuantity(),
 			this.getGravity(), this.draw_zone.getWidth());
@@ -122,6 +146,9 @@ class FXMLViewerController implements EventListener {
 		this.ispace.emit(ievent);
 	}
 
+	/*
+	 * Launch fireworks
+	 */
 	@FXML
 	protected def actionLaunch() {
 		launch_button.setDisable(true);
@@ -135,6 +162,9 @@ class FXMLViewerController implements EventListener {
 		}
 	}
 
+	/*
+	 * Stop fireworks
+	 */
 	@FXML
 	protected def actionStop() {
 		stop_button.setDisable(true);
@@ -143,6 +173,9 @@ class FXMLViewerController implements EventListener {
 		this.ispace.emit(new Freeze(true));
 	}
 
+	/*
+	 * Add a listener on gravity
+	 */
 	@FXML
 	protected def actionGravityDisplay() {
 		gravity_input.valueProperty().addListener [
@@ -150,6 +183,9 @@ class FXMLViewerController implements EventListener {
 		]
 	}
 
+	/*
+	 * Add a listener on rocket quantity
+	 */
 	@FXML
 	protected def actionRocketQuantityDisplay() {
 		rocket_quantity_input.valueProperty().addListener [
@@ -157,6 +193,9 @@ class FXMLViewerController implements EventListener {
 		];
 	}
 
+	/*
+	 * Add a listener on fire quantity
+	 */
 	@FXML
 	protected def actionFireQuantityDisplay() {
 		fire_quantity_input.valueProperty().addListener [
@@ -164,18 +203,18 @@ class FXMLViewerController implements EventListener {
 		]
 	}
 
+	/*
+	 * Get ID of the object on the space
+	 */
 	@Override
 	public def getID() : UUID {
 		return this.id;
 	}
 
+	/*
+	 * Needed for implementing EventListener
+	 */
 	@Override
 	public def receiveEvent(ievent : Event) {
-		/* 
-		 * if (event instanceof TestEvent){
-		 * System.out.println("Guy recieved an event " + ((TestEvent) event).message);
-		 * this.space.emit(new TestEventHack());
-		 * }
-		 */
 	}
 }