• Introduction
• Quick Start
• Interstellar Empires
• Scenarios
• StarSystems
• StarShips
  • WarShip
  • ScanShip
  • Drone
  • EMine
  • SpyShip
  • Freighter
  • InkSpot
  • CloakDetector
  • Tug
  • HijackShip
  • ShieldGenerator
  • CommandShip
  • DoppleShip
  • RepairShip
  • DoomMissile
  • NukeMissile
  • MineSweeper
  • GravShip
  • StarTillery
  • TechShip
  • JumpGateShip
  • BattleStation
  • BeamShip
  • MadBomb
  • Elite
  • ParalyShip
  • RemoteViewer
  • Director
• StarSystem Orders
• StarShip Orders
• Impulses and Movement
• MultiPlayer Games
  • Alliances
• Customizing SV5
• Programming SV5
  • Scenario Programming
    • Dynamic Scenarios
  • Brain Programming
    • StarSystemInfo Class
    • StarShipInfo Class
    • WormholeInfo Class

Programming a Custom Brain

To create a new Brain, create a new Class Library in Visual Studio, or your selected development platform, and add a reference to the SCG.SolarVengeance.Engine assembly.  Then, create a new C# class and derive it from Brain (you will need to add "using SCG.SolarVengeance.Engine" to the class.  You should give the Brain class name the same name as the source code file that you create.

Brain Properties

public abstract string Description
Override this property to return a description of your Brain.  This appears when the Brain is clicked in the Brain list.

The Brain Logic

public abstract void Execute();
Override the Execute method and implement the main Brain logic here.  Solar Vengeance will call the Execute method of your Brain every 10 Impulses.  Your Brain logic will call methods in the Brain API (see below) to build and command StarShips and perform other actions.

The Brain API

These methods should be called from within your Execute method, and allow you to reproduce all of the orders that are available to normal players.  They also expose game state information that the Brain has knowledge of.

Miscellaneous Properties and Methods

protected IList<BlackHoleInfo> BlackHoles
Provides access to a list of BlackHoleInfo objects that represent the Black Holes visible to the Brain.  The BlackHoleInfo object contains a Location property, as well as X and Y properties, all of which return the Black Hole's position.

protected StarSystemInfo Capital
Returns a StarSystemInfo object that represents the Brain's Capital StarSystem.

protected double Distance(int x1, int y1, int x2, int y2)
Calculates the accurate distance between two points.

protected int DistanceQuick(int x1, int y1, int x2, int y2)
Returns a quick calculation of distance between two points by adding the absolute values of the differences of the x and y coordinates.  The performance of this method is much faster than the Distance method.

protected internal StarShipInfo FindStarShip(string code)
This method allows the Brain to locate a StarShipInfo object that has the specified 3-character code.  Each StarShip has a unique 3 character code that can be used to uniquely identify it.  If a StarShip with the corresponding code could not be found, the methods returns null.  This might occur because a StarShip previously identified has been destroyed, or because it is no longer visible to the Brain.

protected internal StarSystemInfo FindStarSystem(string name)
This method allows the Brain to locate a StarSystemInfo object by the name of the StarSystem it represents.  If a corresponding StarSystem could not be found, the methods returns null.

protected TerrainType GetTerrain(int x, int y)
Returns the type of terrain at the specified coordinate.  Possible values are Clear or Nebula.

protected bool IsMultiPlayerGame
Returns true if this game is a MultiPlayer game being played on a PrismServer.

protected bool IsPlayerHuman(string playerName)
Returns true if the specified player is a human.  If the player is being controlled by a computer Brain the method returns false.

protected int MapHeight
protected int MapWidth
These properties return the dimensions of the map playing field.

protected IList<StarShipInfo> MyStarShips
This property provides access to a list of StarShipInfo objects that represent all of the StarShips owned by the Brain.

protected string Name
The Name property returns the name of the Player that is controlling the Brain.

protected IList<string> PlayerNames
Returns a list of player names for all of the players currently in the game (not eliminated.)

protected IList<PulsarInfo> Pulsars
Provides access to a list of PulsarInfo objects that represent the Pulsars that are visible to the Brain.  The PulsarInfo class contains a Location property (Point), and X and Y properties that specify the location of the Pulsar.

protected int Random(int from, int to)
Returns a random integer within a range of values, inclusive of the from and to values.  You can also access a static instance of the Math.Random class in the SVGame class via the RND static property.

protected IList<StarShipInfo> StarShips
This property provides access to a list of StarShipInfo objects that represent all of the StarShips that are currently visible to the Brain.  This includes the StarShips owned by the Brain.

protected IList<StarSystemInfo> StarSystems
This property provides access to a list of StarSystemInfo objects that represent the StarSystems on the map.

protected double TechMultiple
This property returns the current Tech Multiple of the Brain.  Tech Multiple determines how quickly StarSystems generate Resources, and can be increased by building TechShips.

protected IList<WormholeInfo> Wormholes
This property provides access to a list of WormholeInfo objects that represent the Wormholes that are currently visible to the Brain.

StarSystem Command Methods

The Brain uses these methods to perform actions at StarSystems that it owns.  If you call one of these methods using a StarSystem not owned by the Brain, it does nothing.

protected void BuildScanners(StarSystemInfo system, int number)
Instructs the Brain the build Scanners at a StarSystem.

protected void BuildShields(StarSystemInfo system, int number)
Instructs the Brain to build Shields at a StarSystem.

protected void BuildStarShip(StarSystemInfo system, StarShipType shipType, int engines, int value, bool cloaked)
Instructs the Brain to build a StarShip at the specified StarSystem.  The StarShip will be built in one of the available spaces next to the StarSystem, assuming it has enough Resources.

protected void SetAutoScanners(StarSystemInfo system, bool autoScannersOn)
Instructs the Brain to turn auto-Scanner building on or off at a StarSystem.

protected void SetAutoShields(StarSystemInfo system, bool autoShieldsOn)
Instructs the Brain to turn auto-Shield building on or off at a StarSystem.

protected void SetAutoStarShip(StarSystemInfo system, bool autoStarShipOn)
Instructs the Brain to turn auto-StarShip building on or off at a StarSystem.  Use the SetAutoStarShipType method to set the type of StarShip to auto-build.

protected void SetAutoStarShipType(StarSystemInfo system, StarShipType shipType, int engines, int value, bool cloaked)
Sets the type of StarShip that will be built when the Brain turns on auto-build StarShips for the StarSystem specified.

StarShip Command Methods

The Brain calls these methods to command the StarShips that it owns.  If you call one of these methods using a StarShip that the Brain does not own, it does nothing.

protected void AttackAdjacent(StarShipInfo ship, bool attack)
Turns on or off the Attack Adjacent behavior of StarShips.  When on, the StarShip will attack any adjacent enemy StarShip automatically.

protected void BuildStarShip(StarShipInfo ship, StarShipType shipType, int engines, int value, bool cloaked)
Instructs the BattleStation specified in the "ship" parameter to build a StarShip with its accumulated Resources.

protected void ClearOrder(StarShipInfo ship)
Instructs the Brain to clear any current order that the StarShip might have.

protected void CreateJumpGate(StarShipInfo ship)
Instructs a JumpGateShip to create a JumpGate at its current location.  A JumpGate will be created only if one was not already created by a JumpGateShip that was created at the same StarSystem as the ship being commanded here.

protected void Defend(StarShipInfo ship, StarSystemInfo system)
protected void Defend(StarShipInfo ship, StarShipInfo defendShip)
protected void Defend(StarShipInfo ship, Point pt)
Instructs the StarShip to defend the specified target StarSystem, StarShip, or point on the map.  This behavior is the same as the Defend manual order for StarShips.  This order will only succeed if the StarShip is capable of attacking other StarShips.

protected void DetonateMadBomb(StarShipInfo ship)
The Brain can detonate any MadBombs that it sees and identifies on the map, whether they belong to the Brain's player or not.

protected void Escort(StarShipInfo ship, StarShipInfo escortTarget, int offsetX, int offsetY)
Instructs the StarShip to perform the Escort order for the target StarShip, using the specified X and Y offsets for formation.

protected void Move(StarShipInfo ship, int x, int y)
Instructs the StarShip to move the specified coordinates.  If the coordinates are off the map, they are truncated to within the map dimensions.

protected void SetRemoteViewPoint(StarShipInfo ship, int x, int y)
Sets the space on the map that a RemoteViewer will view.  Once this is set, calling this method again will not change it.

protected void Target(StarShipInfo ship, StarSystemInfo system)
Instructs the StarShip to target the specified StarSystem.  This order applies not only to WarShips and other StarShips that can attack StarSystems, but also to ships like GravShips and ShieldGenerators.

protected void Target(StarShipInfo ship, StarShipInfo target)
Instructs the StarShip to target the specified enemy StarShip.  This order applies not only to WarShips and other StarShips that can attack StarShips, but also to ships like RepairShips and Tugs.

protected void Transport(StarShipInfo ship, StarSystemInfo from, StarSystemInfo to)
Instructs the Freighter to transport Resources from one StarSystem to another.

protected void TransportBS(StarShipInfo ship, StarShipInfo battleStation, StarSystemInfo to)
Instructs the Freighter to transport Resources from a BattleStation to a StarSystem.

protected void Release(StarShipInfo ship)
Instructs the GravShip to release the StarSystem it is dragging, or the Tug to release the StarShip it is tugging.

Finding Closest Items

One of the things Brains need to frequently do is find the closest StarSystem or StarShip to a specific location.  The following methods provide a flexible way to achieve this.

protected StarSystemInfo ClosestStarSystem(int x, int y, int maxDistance, FindSystemFlags findType)
Returns the closest StarSystem within the specified range (maxDistance).  Use the findType parameter to determine what types of StarSystems to consider in the search.  This is a enum flags type that has the following possible values:

public enum FindSystemFlags
{
    Owned = 1, Independent = 2, NonVisible = 4, Allied = 8, Enemy = 16,
    All = Owned + Independent + NonVisible + Allied + Enemy,
    Visible = Owned + Independent + Allied + Enemy,
    Friendly = Owned + Allied,
    Unfriendly = Independent + NonVisible + Enemy,
    VisibleUnfriendly = Independent + Enemy
};

protected StarShipInfo ClosestStarShip(int x, int y, int maxDistance, FindShipFlags findType, ShipKnownFlags known)
Returns the closest StarShip within the specified range (maxDistance).  The findType limits the type of StarShip to include in the search.  It is an enum flags type with the possible values of Owned, Allied, and Enemy.  Owned and Allied states are exclusive; Allied does not include StarShips that you own.  Use the Friendly value (Owned + Allied) to include all friendly StarShips in the search.  The final parameter determines whether to include StarShips that have been identified by the Brain, those that have not, or either.

Alliance Related

protected AllianceLevel AlliedWith(string playerName)
This method returns the current state of alliance that the Brain has toward the Player with the specified name.  AllianceLevel is an enum type that has values of None, NonAggression, Intelligence, and Formal to represent the 3 alliance levels.

protected AllianceLevel AlliedWithMe(string playerName)
This method allows the Brain to determine if other Players have allied with it.

protected void SetAlliance(string playerName, AllianceLevel al)
This method allows the Brain to set an alliance with the Player specified by name.

Brain Data

The Brain Data facility gives you the ability to save local variables that your Brain uses to the saved game file when a game is saved, and restore them when a game is loaded.  Using this facility is not strictly necessary, you can always let your Brain re-learn its state when a saved game is loaded.  But if you wish to save Brain-related data, use the methods below.

public virtual string GetBrainData()
Override this method if you wish to save local variable information of the Brain in a save game file.  The data must be packed into a single string, and returned in this method.

public virtual void ParseBrainData(string brainData)
This method will be called by SV5 when a save game file is loaded and your Brain had used GetBrainData to specify data to save in the file.  You are provided the string that you previously returned in the GetBrainData method.  Parse the string into your Brain's local variables.

Interfacing with MultiPlayer Chat

Your Brain can interact with MultiPlayer chat in the Diplomacy interface by using the methods below.

public virtual void IncomingMessage(string playerName, string message)
SV5 calls this method whenever an incoming chat message was sent to the Player your Brain is controlling.  To receive these messages, override this method in your Brain code.  If you wish to use this message somehow in your Execute method, you need to save it to a local variable or List.  If you do this, be sure that you provide thread-safe access to the local variable used, because the incoming message is received in a different thread than the one that executes your Execute method.

protected void SendMessage(ChatChannel channel, string msg)
Call this method to send a line of chat to other Players in a MultiPlayer game.  You can call this in response to IncomingMessage, above, or in the Execute method.  The ChatChannel parameter controls who the message will be sent to, and can have the value of All, Friendly, or Enemy.