Class GSTrackSearch
From TrainzOnline
(Difference between revisions)
m |
m (→Code Examples: Typo on the GetDistance(); method) |
||
| Line 86: | Line 86: | ||
MapObject mo = gst.SearchNext(); // initiate the search | MapObject mo = gst.SearchNext(); // initiate the search | ||
while (mo) { // continue as long as objects are present | while (mo) { // continue as long as objects are present | ||
| − | float distance = | + | float distance = gst.GetDistance(); // how far ahead the object is |
if (distance() > 1000.0) break; // break from the loop if the distance exceeds 1km | if (distance() > 1000.0) break; // break from the loop if the distance exceeds 1km | ||
Interface.Print("object found at " distance " metres"); // print out the results | Interface.Print("object found at " distance " metres"); // print out the results | ||
Revision as of 14:41, 7 June 2011
- API Hierarchy
- GSTrackSearch
- A class enabling the searching of a length of track for Trackside items.
- The GSTrackSearch class provides an interface to access certain items along a track in a specified direction from an existing trackside item.
- A GSTrackSearch object can be obtained by calling the BeginTrackSearch() method on the Trackside item that you want to start your search from.
- The SearchNext() and GetMapObject() methods are provided to get a reference to a discovered Trackside object.
- The reference returned by these methods can be cast to Trackside child classes to find out if that item is in fact a Signal or a Junction for instance. As the script code doesn't know what the next item will be, always verify the cast.
- Since Vehicles and Locomotives descend from Trackside, searches can be initiated from rolling stock and rolling stock will be returned.
- GSTrackSearch methods will also find SceneryWithTrack and descendants, although the information which can be obtained from them is limited and these objects cannot be used to initiate a search.
- The search will continue (following the direction set by any junctions) until it is blocked by:
- A junction set against the track
- A turntable.
- A crossing. *** ? "crossing" appears to mean a track (diamond, etc), rather than a road (grade, level) crossing, since the function appears to work properly across road crossings.
- The end of the line.
- See TrackSearch for details of enhancements being developed for future versions of the game.
Contents |
Trackside.BeginTrackSearch
public native GSTrackSearch Trackside.BeginTrackSearch(bool direction)
- This method is called on objects descending from the Trackside class to obtain a GSTrackSearch object in the specified search direction.
- See Trackside.BeginTrackSearch() for details.
GetDistance
public native float GetDistance(void)
- Parameters
- None
- Returned Value
- The distance in metres from the origin of the search to the object at which the search cursor is currently pointing.
- Syntax
float distance = gst.GetDistance();
- Notes
- See Code Examples
GetFacingRelativeToSearchDirection
public native bool GetFacingRelativeToSearchDirection(void)
- Parameters
- None
- Returned Value
- True if the returned object orientation matches the direction of search, false otherwise.
- Syntax
bool facing = gst.GetFacingRelativeToSearchDirection();
- Notes
- Note that it is the direction of the search that matters, not the facing direction of the search origin.
- A search forwards from a fixed object such as a Trigger will return true for any returned trigger which has the same orientation as the source.
- A search backwards from a fixed object such as a Trigger will return false for any returned trigger which has the same orientation as the source.
GetMapObject
public native MapObject GetMapObject(void)
- Parameters
- None
- Returned Value
- A reference to a MapObject or null if nothing has been found.
- Syntax
MapObject mo = gst.GetMapObject();
- Notes
- MapObject returns Trackside descendants including Vehicles and SceneryWithTrack descendants including Industries.
- Ensure that you attempt a cast to SceneryWithTrack and Trackside if you want the maximum possible amount of information from the search.
SearchNext
public native MapObject SearchNext(void)
- Parameters
- None
- Returned Value
- A reference to a MapObject or null if nothing has been found.
- Syntax
MapObject mo = gst.GetMapObject();
- Notes
- SearchNext moves the search cursor to the next object if such an object exists.
Known Issues
- GSTrackSearch will return a null reference if it finds certain types of Crossing objects, but will continue searching beyond them if asked. As a result of this it is often necessary to make repeated calls to SearchNext following a null return to decide whether you have reached the end of the track or whether your search has simply been interrupted by one or more crossings.
Code Examples
- This code fragment implements a search forwards from a locomotive. The distance from the locomotive to any discovered object is printed to jetlog.txt
- The process continues until the search returns a null value (which might be a crossing or the end of the track) or the distance from the train exceeds 1km.
GSTrackSearch gst = Loco.BeginTrackSearch(true); // obtain a GSTrackSearch object
MapObject mo = gst.SearchNext(); // initiate the search
while (mo) { // continue as long as objects are present
float distance = gst.GetDistance(); // how far ahead the object is
if (distance() > 1000.0) break; // break from the loop if the distance exceeds 1km
Interface.Print("object found at " distance " metres"); // print out the results
mo = gst.SearchNext(); // search for the next object
}
Related Methods
