• 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 Scenario

To create a new Scenario, 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 Scenario (you will need to add "using SCG.SolarVengeance.Engine" to the class.  You should give the Scenario class name the same name as the source code file that you create.

Scenario Properties

There are a number of virtual and abstract properties you can (or must, for abstract) override in your Scenario.

public virtual bool AssignCapitals
The default value of this property is true, and instructs SV5 to assign Capitals to Players if they are not assigned by the time the Scenario is created.  If you disable this, then Players will not have Capitals unless you assign them explicitly in the BuildScenario method.  You may need to do this, for example, if your Scenario creates fleets of StarShips only, with no StarSystems.  When taking this route, you should code your own Victory Conditions in the VictoryReached method.

public virtual string Author
Override this property to return your name, or Star Lord name.  You want to get proper credit for your creation!

public virtual int CapitalValue
Optionally override this property to specify a default value for players Capital StarSystems.  The default value is 20, as is the maximum allowed.  This value appears in the edit control for Capital Values when the Scenario is selected.

public virtual int DefaultResources
Optionally override this property to specify the amount of Resources that players' Capital StarSystems should get at the start of the game.  The default value is 100 and the maximum is 1,000.  This value appears in the edit control for Capital Resources when the Scenario is selected.

public virtual bool CapitalElimination
The default value of this property is true.  If you override and set to false, then a player is not eliminated from the game when their Capital is conquered.  If you do this, be sure to specify your own custom Victory Conditions by overriding the VictoryReached method.

public virtual int CapitalShields
Optionally override this property to change the number of Shields that players' Capital StarSystems start with from the default value of 10.

public virtual int CapitalScanners
Optionally override this property to change the number of Scanners that players' Capital StarSystems start with from the default value of 10.

public abstract string Description
Override this property to return a description of the Scenario that appears when it selected from the list.

public virtual Size MapSize
Optionally override this property to set a map size other than the standard 100x100.

public virtual int MaxPlayers
Optionally override this property to change the maximum number of players that the Scenario can accommodate.  The default value is 10.

Adding/Disallowing StarShip Types

You can control what StarShip types are added and disallowed in your Scenario by using the two methods below.  Create a List<StarShipType> and return it in these properties.  StarShipType is an enum that contains the 28 StarShip types.

public virtual IList<StarShipType> AddedStarShipTypes
Return a list of StarShipTypes that should be automatically added to each player's available list at the start of the game.

public virtual IList<StarShipType> DisallowStarShipTypes
Return the StarShipTypes that should not be allowed in this Scenario.  These StarShipTypes will be removed from players' selections at the start of the game.

Miscellaneous Methods

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.

public virtual void Initialize()
SV5 calls the Initialize method before the game starts, including for all players in a MultiPlayer game.  You can use this opportunity to display a Scenario-specific message box, for example.

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.  You should not use this Random method from within the ProcessImpulse method (see below).  Instead, use the new DS_Random method to generate random numbers.

The Game Property

public SVGame Game

This property returns an instance of an SVGame class.  The SVGame class contains all of the internal objects currently created in the game.  It has a List of StarShip objects called StarShips, a List of StarSystem objects called StarSystems, etc.  You can use the Game property to access information about the current state of the Scenario in the BuildScenario and the VictoryReached methods (see below).

You can also modify the internal game state within the ProcessImpulse method (see below).  The best way to learn about what's in the SVGame class is to explore its properties and methods with Intellisense from Visual Studio, all of the information is fairly self-documenting.  If you have questions please post them on the Silicon Commander Games message board.

The BuildScenario Method

public abstract void BuildScenario(int numPlayers, int capitalValues, int startingResources);
You will override the BuildScenario method and here include the logic that actually creates the Scenario map, using the various methods in the Scenario API described below.

The Scenario API

The Scenario API includes a set of methods that you can use in your implementation of BuildScenario to create StarSystems, StarShips, Nebula, and anything else you need to place in the Scenario.  For more advanced control, it might be required to access the SVGame object provided by the Game property.  But for most applications you should be able to achieve what you need with the Scenario API.

protected void CreateBlackHole(int x, int y, int radius)
Creates a Black Hole at the specified location, with the specified radius.  The radius indicates how close StarShips must be to begin to be pulled into the Black Hole.

protected void CreateNebula(int x, int y, int numArms, int numCells)
This method is deprecated.  Use CreateTerrain instead to create a variety of possible terrains, including Nebula.

protected void CreatePulsar(int x, int y)
Creates a Pulsar at the specified coordinates.

protected void CreateStarCluster(int numStarSystems, int x1, int y1, int x2, int y2, int radius, int density)
Call this method to produce a StarSystem cluster in the Scenario.  The cluster will create StarSystems along a line specified by the coordinates x1,y1 to x2,y2.  The coordinates pairs can both be the same to create a purely globular cluster.  The radius parameter determines the maximum distance that StarSystems will be produced away from the line/point.  The density parameter determines how many times the generated StarSystem positions are averaged together, leading to more highly dense clusters as the value increases.

protected StarShip CreateStarShip(int x, int y, Player owner, StarShipType shipType, int engines, int extra, bool cloaked)
Creates a StarShip at the specified location, using the parameters to determine its StarShip type, Engines, and Primary System values (the "extra" parameter), as well as whether or not it should be cloaked.  The Player property indicates the owner of the StarShip, and is an object of the Player class.  You can access the Player objects via the Players property of the Game property.  The Players property is a List<Player>.

Example:

Player p = Game.Players[0];
CreateStarShip(50, 50, p, StarShipType.WarShip, 20, 10, true);

protected StarSystem CreateStarSystem(int x, int y, int value, int shields, int scanners, double resources)
Creates a single StarSystem at the location specified in x,y.  If there was already an object at that location and the StarSystem could not be created, this method returns null.  Specify the properties of the StarSystem in the parameters.  To perform further modification of the StarSystem, set the properties in the StarSystem object that is returned by this method.

protected void CreateTerrain(TerrainType tt, int x, int y, int numArms, int numCells)
Creates a random span of terrain of the specified type.  The current possible values of TerrainType are Clear and Nebula.  The terrain mass is centered on the coordinates specified in x and y, and is randomly generated by moving a virtual pen around the map in random directions, for a number of times equal to the numCells parameter.  The process is repeated, starting back at the origin, for a number of times specified by the numArms parameter.

protected ScenarioImage CreateTerrainImage(TerrainType tt, string imageFileName, int x, int y, double alpha)
Allows you to provide custom background images that will be displayed on the map, and optionally converted to terrain elements.  Image files that are used as backgrounds must be in the "Scenarios" folder under the main SV5 install folder.  Provide the name of the image file, with extension, in the imageFileName property.  The x and y properties determine the coordinates where the image will be drawn on the map, specified in game map coordinates.  If the tt property contains a terrain other than "Clear", the image will be examined cell by cell.  A cell is a 30x30 pixel block that maps to a coordinate on the playing map.  If a cell contains any non-black pixels, the corresponding map cell will be set to the specified terrain (currently the only terrain available is Nebula.)  The alpha property specifies a transparency level to apply when rendering the image.  Specify 1.0 for a fully opaque image.  Values less that 1.0 indicate levels of transparency to apply to the image, which can lead to more pleasing effects when rendering cosmic images to the map.  The method returns an instance of a ScenarioImage object, which you normally do not need to worry about.  However, you can manipulate the Visible property of this object to show/hide images on the map.  You might save this object to a local variable and manipulate it from the CheckVictory method, for example.

protected void CreateWormhole(int x1, int y1, int x2, int y2)
This method creates a Wormhole at location x1,y1, with a destination point at x2,y2.

protected TerrainType GetTerrain(int x, int y)
Returns the terrain at the specified location.  TerrainType is an enum with possible values of Clear and Nebula.

protected void SetTerrain(int x, int y, TerrainType terrain)
Allows you to set the terrain on a coordinate by coordinate basis.

Assigning Capitals

protected bool AssignCapital(Player player, Rectangle area)
You can call this method after all of your StarSystems are created to attempt to assign a Capital to a Player within an area of the map specified in the area parameter.  This method is useful for assigning Capitals to alternating sides of the map, for example.  See DoubleCluster.cs for an example of this technique.

You can also go through the StarSystems created manually using Game.StarSystems and Game.Players, and assign capitals manually.  To assign a Capital, set the Player.Capital property to the desired StarSystem.  See MirrorImage.cs for an exmaple of explicitly setting Player Capitals.

If you fail to set Capitals in your Scenario code, do not worry.  SV5 does it automatically for you for Players who do not have Capitals after your BuildScenario code executes.

Victory Conditions

public virtual bool VictoryReached()
If you override this method, you can have your Scenario specify its own specific victory conditions.  This method is called after each Impulse is processed in Solar Vengeance.  In this method you can examine the current game state by accessing the Game property, which is an instance of the SVGame class and contains the current state of the game.  You can examine the game state by reading properties in the Game object, but do not try and change property values here.  If you do, the changes will not be communicated to other players in a MultiPlayer game.  See the ProcessImpulse method below for a way to alter the game state from within your Scenario class.

In you have determined that your custom victory conditions have been reached, you should set the Victor property to true for each Player object that has met the conditions, and return true from this method.

If your custom victory conditions have not been met, and you want to keep the default victory condition of Player elimination, be sure to return base.VictoryReached in your implementation.

See the Scenario XMarksTheSpot.cs for an example of how to code a custom Victory Condition.

Dynamic Scenarios