diff --git a/examples/src/OpenDis7Examples/ExampleSimulationProgram.java b/examples/src/OpenDis7Examples/ExampleSimulationProgram.java
index b192753e43df9c28f58688b0a1a650a78b792acb..77dac690fff2a32c4ae8e629ac3142f7466e5d18 100644
--- a/examples/src/OpenDis7Examples/ExampleSimulationProgram.java
+++ b/examples/src/OpenDis7Examples/ExampleSimulationProgram.java
@@ -1,6 +1,7 @@
/**
* Copyright (c) 2008-2021, MOVES Institute, Naval Postgraduate School (NPS). All rights reserved.
* This work is provided under a BSD open-source license, see project license.html and license.txt
+ * @author brutzman@nps.edu
*/
package OpenDis7Examples;
@@ -24,60 +25,66 @@ import java.util.logging.Logger;
public class ExampleSimulationProgram
{
/**
- * This runSimulation() method is for you! This block is programmer-modifiable method
- * for defining and running a new simulation of interest.
- * Support include DIS EntityStatePdu, FirePdu and CommentPdu all available for
+ * This runSimulation() method is for you, a
+ * programmer-modifiable method for defining and running a new simulation of interest.
+ * Welcome! Other parts of this program handle bookkeeping and plumbing tasks so that
+ * you can focus on your model entities and activities.
+ * Expandable support includes DIS EntityStatePdu, FirePdu and CommentPdu all available for
* modification and sending in a simulation loop.
* Continuous improvement efforts seek to make this program as easy and straightforward
- * as possible for new simulationists to use and adapt.
- * All of the other methods are setup, teardown and configuration that you don't have to worry about.
+ * as possible for DIS simulationists to use and adapt.
+ * All of the other methods are setup, teardown and configuration that you may find
+ * interesting, even helpful, but don't really have to worry about.
*/
- @SuppressWarnings("SleepWhileInLoop")
+ @SuppressWarnings("SleepWhileInLoop") // yes we do that
public void runSimulation ()
{
try
{
/** seconds for real-time execution (not simulation time, which may or may not be the same) */
- final double LOOP_DURATION_SECONDS = 1.0;
- final int MAX_LOOP_COUNT = 10; // be deliberate out out there!
- int loopCount = 0; // initialized at 0
- boolean simulationComplete = false; // sentinel variable as termination condition,, are we done yet?
+ final double SIMULATION_LOOP_DURATION_SECONDS = 1.0;
+ final int SIMULATION_MAX_LOOP_COUNT = 10; // be deliberate out out there! also avoid infinite loops.
+ int simulationLoopCount = 0; // variable, initialized at 0
+ boolean simulationComplete = false; // sentinel variable as termination condition,, are we done yet?
// TODO reset clock to zero each time for consistent outputs
- // your model setup: who's who in this zoo?
- // create PDU objects and set their values
+ // Your model setup: define participants. who's who in this zoo?
+ // Assuming you keep track of entity objects... here is some support for for Entity 1.
+ // create PDU objects and set their values.
EntityID entityID_1 = new EntityID();
entityID_1.setSiteID(1).setApplicationID(2).setEntityID(3); // made-up example ID;
- // TODO use enumerations; is there a unique site triplet for MOVES Institute?
+ // TODO someday, use enumerations; is there a unique site triplet for MOVES Institute?
- EntityStatePdu entityStatePdu = pduFactory.makeEntityStatePdu();
- entityStatePdu.setEntityID(entityID_1);
+ EntityStatePdu entityStatePdu_1 = pduFactory.makeEntityStatePdu();
+ entityStatePdu_1.setEntityID(entityID_1);
- FirePdu firePdu = pduFactory.makeFirePdu();
+ FirePdu firePdu_1a = pduFactory.makeFirePdu(); // for entity 1 first weapon (if any)
+ FirePdu firePdu_1b = pduFactory.makeFirePdu(); // for entity 1 second weapon (if any)
// should we customize this munition? what is it for your simulation?
- // TODO simulation management PDUs for startup
+ // TODO simulation management PDUs for startup, planning to design special class support
// loop the simulation while allowed, programmer can set additional conditions to break out and finish
- while (loopCount < MAX_LOOP_COUNT) // are we done yet?
+ while (simulationLoopCount < SIMULATION_MAX_LOOP_COUNT) // are we done yet?
{
- loopCount++; // good practice: increment loop counter as first action
+ simulationLoopCount++; // good practice: increment loop counter as first action in that loop
// =============================================================================================
- // your own simulation code starts here!
+ // * your own simulation code starts here! *
+ // =============================================================================================
// are there any other variables to modify at the beginning of your loop?
// compute a track, update an ESPDU, whatever it is that your model is doing...
- // Where is my entity? Insert changes in position.
- entityStatePdu.getEntityLocation().setX(entityStatePdu.getEntityLocation().getX() + 1.0); // 1m per timestep
-
+ // Where is my entity? Insert changes in position; this sample only changes X position.
+ entityStatePdu_1.getEntityLocation().setX(entityStatePdu_1.getEntityLocation().getX() + 1.0); // 1m per timestep
+
// decide whether to fire, and then update the firePdu. Hmmm, you might want a target to shoort at!
- // etc. etc. your code goes here
+ // etc. etc. your code goes here for your simulation of interest
// something happens between my simulation entities, la de da de da...
System.out.println ("... My simulation just did something, no really...");
@@ -85,37 +92,38 @@ public class ExampleSimulationProgram
// make your reports: narrative code for CommentPdu here (set all to empty strings to avoid sending)
narrativeMessage1 = "MV3500 ExampleSimulationProgram";
- narrativeMessage2 = "runSimulation() loop " + loopCount;
+ narrativeMessage2 = "runSimulation() loop " + simulationLoopCount;
narrativeMessage3 = ""; // intentionally blank for testing
// your loop termination condition goes here
- if (loopCount > 4) // for example
+ if (simulationLoopCount > 4) // for example
{
simulationComplete = true;
}
- // your own simulation code is finished here!
+ // =============================================================================================
+ // * your own simulation code is finished here! *
// =============================================================================================
- // keep track of timestep: wait duration for elapsed time in this loop
+ // staying synchronized with timestep: wait duration for elapsed time in this loop
// Thread.sleep needs a (long) parameter for milliseconds, which are clumsy to use sometimes
- Thread.sleep((long)(LOOP_DURATION_SECONDS * 1000)); // seconds * (1000 msec/sec) = milliseconds
- System.out.println ("... [Pausing for " + LOOP_DURATION_SECONDS + " seconds]");
+ Thread.sleep((long)(SIMULATION_LOOP_DURATION_SECONDS * 1000)); // seconds * (1000 msec/sec) = milliseconds
+ System.out.println ("... [Pausing for " + SIMULATION_LOOP_DURATION_SECONDS + " seconds]");
- // send the status PDUs for this loop and continue
- System.out.println ("sending PDUs for simulation step " + loopCount + ", monitor loopback to confirm sent");
- sendAllPdusForLoopTimestep(entityStatePdu, firePdu, timeStepComment, narrativeMessage1, narrativeMessage2, narrativeMessage3);
+ // OK now send the status PDUs for this loop, and then continue
+ System.out.println ("sending PDUs for simulation step " + simulationLoopCount + ", monitor loopback to confirm sent");
+ sendAllPdusForLoopTimestep(entityStatePdu_1, firePdu_1a, timeStepComment, narrativeMessage1, narrativeMessage2, narrativeMessage3);
System.out.println ("... [PDUs successfully sent for this loop]");
// ===============================
- // loop now finished, thus terminate if simulation complete, otherwise send latest PDUs and continue
- if (simulationComplete || (loopCount > 10000)) // for example; including fail-safe condition is good
+ // loop now finished, check whether to terminate if simulation complete, otherwise continue
+ if (simulationComplete || (simulationLoopCount > 10000)) // for example; including fail-safe condition is good
{
System.out.println ("... [Termination condition met, simulationComplete=" + simulationComplete + "]"); // ", final loopCount=" + loopCount +
break;
}
- } // end of while loop
- // all done
- narrativeMessage2 = "runSimulation() completed successfully";
+ } // end of simulation loop
+
+ narrativeMessage2 = "runSimulation() completed successfully"; // all done
sendCommentPdu(narrativeComment, narrativeMessage1, narrativeMessage2, narrativeMessage3);
System.out.println ("... [final CommentPdu successfully sent for simulation]");
// TODO simulation management PDUs
@@ -133,6 +141,7 @@ public class ExampleSimulationProgram
String narrativeMessage3 = new String();
/* VariableRecordType enumerations have potential use with CommentPdu logs */
+ /* TODO contrast to EntityType */
VariableRecordType descriptionComment = VariableRecordType.DESCRIPTION;
VariableRecordType narrativeComment = VariableRecordType.COMPLETE_EVENT_REPORT;
VariableRecordType statusComment = VariableRecordType.APPLICATION_STATUS;