DPRSim: the Dynamic Physical Rendering Simulator

New! Download a Catom API Cheatsheet HERE [23kb, PDF].

The Catom API is the series of method calls and variables that a catom programmer has "legal" access to. When we say legal, we mean the data that represents information that a Catom would have in real life. The Data Structures in the simulator are organized as follows:

CatomWorld --> CatomSim --> Catom

CatomWorld contains all of the information about the environment and physical settings, as well as the thread management, physics and graphics for the simulator. CatomSim is a wrapper for the simulated Catom that contains Simulator specific information such as true 3D location and rotation. Catom is the data structure that represents a real Catom. It defines the API that is available to catom programmers. For example, in a valid catom program, you can't simply look into the CatomSim data structure to determine your location, this is not information that a Catom would have readily available in reality. Therefore, we have an API call Catom->getLocation() that returns where the Catom _thinks_ it is. For now this API simply queries the simulator and returns the correct location, but this is not guaranteed to hold forever. In the future we can imagine a service rtunning on the catom that attempts to keep track of its location and re-localize through communication if it fails, and then the API would query this service, but the API call itself will not change.

This page contains brief descriptions of all of the available API calls.

Catom::getID() returns the GUID (clobal unique identifier) for the Catom.

Catom::getLocation() returns a Point3D location in space.

Catom::setBatteryLife(double) updates the values returned by getBatteryLife().

Catom::getBatteryLife() returns the number of "ticks" of battery life left, which determines how long a Catom can operate when disconnected from the ensemble

Catom::getNeighborCenter(FID) calculates the location of a hypothetical Catom, if it were attatched to feature FID, based on the Catoms current location and rotation.

Catom::getNeighbors() forces a refresh of the internal neighbor list of a Catom, which defines which Catoms are currently touching this Catom. In reality this would represent polling its sensors on the contact points to see which ones are engaged.

Catom::getNeighbor(FID) returns a CatomID of the neighbor touching the Catom at feature FID.

Catom::addNeighbor(FID,CatomID) adds a neighbor identified by CatomID to feature FID.

Catom::removeNeighbor(CatomID) removes this Catom from the neighbor list, if it is present there.

Catom::clearNeighbors() clears the neighbors list of all entries.

Catom::getNearestFeature(Point3D,CatomID) determines the closest FID to this point in space.

Catom::getFeatureTouching(CatomID,CatomID) returns which of your FIDs is touching a given Catom.

Catom::setColor(r,g,b) turns the Catom a particular color (valid values for rgb are 0..255)

Catom::amPowered() returns true or false, based on the power connectivity of the Catom.

Catom::amOnFloor() returns true of false, depending on wheather the Catom has sensed it is touching the floor.

Catom::amOnSurface() this API call is currenlty ill-defined, it is intented to return true of false depending on whether many of the Catom's feature IDs are unoccupied.

Catom::amMobile() this API call is intended to return true or false depnding on whether any movement is currently possible. If a Catom is embeded in an emsemble, then it is not mobile.

There is one more API call, and I want to separate it out because it is clearly "illegal" but is a neccessary evil for now, and it is magic move:

Catom::moveTo(catomID,FID) magically moves you to a position and rotation consistant with being in contact with Catom CatomID at Feature FID. There are no rules associated with the values for CatomID and FID. Therefore we call this Magic-Move. When you use this API call you WILL be moved to the location you ask for instantly. In the future the simulator may only allow CatomID to be a catom you are currently touching, and more aggressively FID may be forces to only be a direct featureNEighbor on the FeatureMap, allowing only small, direct hops. This API call returns true if the move was successful (always returns true for now). The world should be locked when using this API call or else bad things can happen due to concurency bugs.

Now all of this comes down to how you use it. This API is meant to be used in your CodeModuleName::newTick() and endTick() methods. At the beginning of your newTick() and endTick() functions you should have the line:

Catom* thisCatom = &(worldPtr->catomHash[hostCatom]->C);

Now you will call the API methods as follows:

thisCatom->getLocation();
thisCatom->setColor(r,g,b);
etc...

If you still require some "cheating" information, you could just do:

#define HOSTCATOMSIM = worldPtr->catomHash[hostCatom];
HOSTCATOMSIM->magnet_mode[1];
#define HOSTCATOM = worldPtr->catomHash[hostCatom]->C;
HOSTCATOM.getLocation();
etc...

"HOSTCATOMSIM" is now a pointer to the CatomSim object that contains the Catom in question. As defined earlier, the CatomSim has access to more information (simulator info) than a Catom should have in reality.