Development:Python:Functions - Revision history

Nikai: update

2010-07-11T08:11:59Z

update

Pyramid: /* News */

2008-12-20T18:22:54Z

‎News

Pyramid: /* Getting Units */

2008-12-20T18:19:40Z

‎Getting Units

Pyramid: /* Communications */

2008-12-20T18:18:39Z

‎Communications

Pyramid: /* Communications */

2008-11-17T11:47:35Z

‎Communications

pyramid: /* Flight Groups */

2008-08-28T08:52:23Z

‎Flight Groups

pyramid at 10:34, 22 April 2008

2008-04-22T10:34:47Z

New page

=Useful Python Functions=

Most of the python bindings (to the c++ engine) are listed in <code>data4.x/modules/stub/VS.py</code> and commented in [[HowTo:Edit_Missions:Python:Bindings:Python]].

There are many other useful functions coded in python and distributed through various other classes.
* <code>data4.x/modules/Vector.py</code> contains vector manipulation functions
* <code>data4.x/modules/universe.py</code> has functions related to the current and adjacent systems
* <code>data4.x/modules/unit.py</code> provides some unit properties, methods, and actions
* <code>data4.x/modules/launch.py</code> is useful for spawning units in almost any place
* <code>data4.x/modules/faction_ships.py</code> allows for a fine creation of ship lists by type and faction, e.g. for spawning.
Some of the functions that might be of help when writing quests and adventures are discussed in the following.

==Game Properties and Actions==
* <code>self.starttime = VS.GetGameTime()</code> - get the time since the start of the game. This is not the universe time (star date).

==Getting Units==
In the script you will require to reference the ships and other objects of the universe. Here are some examples to get you started:
* <code>self.player = VS.getPlayer()</code> - that's you
* <code>self.planet = unit.getUnitByName('Atlantis')</code> - get planet Atlantis
* <code>self.station = unit.getUnitByName('MiningBase')</code> - get the mining base
* <code>self.object = unit.getUnitByName('Jump_To_Nethuuleil')<code> - get the jump point
* <code>self.vessel = unit.getUnitByName('Ox')</code> - get an Ox ship
* <code>self.gf = VS.launch("Charlotte the Harlot","Robin","privateer","unit","default",1,1,(1000,10,3000),'')</code> - creates one ship of type "Robin", being of the faction "privateer", at position (1000,10,3000), which will behave like "default" and show up in the HUD as "Charlotte the Harlot"

* <code>ships = VS.getUnitList()</code> - get a list of all objects in the current system
* <code>self.jump = universe.getRandomJumppoint()</code> - get a random jump point
* <code>self.vessel.GetTarget()</code> - get the vessel's targeted unit

==Unit Properties==
Once you have referenced the appropriate object, you want to get information about it. Again, some commented examples follow:
* <code>self.planet.isDocked(self.player)</code> - verify if the player is docked to the planet. Note that you need to 'read' the meaning from right to left in this case.
* <code>self.station.getDistance(self.player)</code> - The distance to the center of an object. Note that when landed on a planet, the distance is the actual planet radius.
* <code>vec = self.player.Position()</code> - assign the player's position vector to a variable
* <code>self.vessel.getName()</code> - gets the unit name, e.g. "Llama"
* <code>self.vessel.getName()</code> - returns the full name of the vessel

==System Properties==
* <code>VS.getSystemName()</code> - get the name of the current system the player is in
* <code>VS.getNumUnits()</code> - get the number of units in the current system. This includes ships, navpoints, cargo, planets, stations, and the sun.

==Communications==
Sending messages through the comm is fairly easy:
* <code>VS.IOmessage (0,"Oxen","all","Hi buddy.")</code> - make the vessel send a message to all through the comm immediately (the first 0) when the script line is executed.
* <code>VS.IOmessage (10,"You","all","Do I know you?")</code> - makes the player send a public message through the comm 10 seconds after the script line is executed.

You can even set your own color for the messages with a html color code:
* <code>VS.IOmessage (20,"Oxen","You","#8080FFYou don't remember me?")</code> - prints the comm message in light blue.
** <code>self.txtColor="#8080FF"</code>
** <code>VS.IOmessage (30,"Oxen","Privateer",self.txtColor+"I can hardly believe this")</code> - you can even define a color variable and add it to each line.

As far as the communications go, there is a variable in cockpit that holds what the VDU screen shows as possible options. Unfortunately the communications system is not scriptable at the moment.

Comm animations can be called from your quest script and will be shown on the Comm VDU:
* <code>self.player.commAnimation("com_questname_animationname.ani")</code>
The animation files must be placed in a corresponding folder <code>data4.x/animations/com_questname_animationname.ani</code> and the animation definition file named equally ''com_questname_animationname.ani''.

==News==
Note that we should eventually make the news reports line up with the quests... :-) I have some ideas how to do that. Basically you can call

<pre>
VS.IOmessage ("game","news","A drone was sighted in the delta prime...blah blah blah")
</pre>
and then people will see it in the game when they click on GNN likewise if you send it to

<pre>
VS.IOmessage ("game","bar","A drone was sighted in the delta prime...blah blah blah")
</pre>
then you can hear it when you talk to the bartender :-)

==More Topics==
{{Fixme}} Improve/expand it.

==Flight Groups==

* <code>ship.getFlightgroupName()</code> - returns the name of the flight group for the ship

You can use "flight group directives" to give units specific orders (which is cool if you want to generate two drones and make one blow up another). The list of directives is in C++ (undocumented).

A capital letter overrides the AI script, while a lower case letter will allow it to be changed. You can also add a "." to the end to ensure that the unit will not change targets on its own.

The following directives are available:
* H, h (help) -- leader of flightgroup requests help.
* B, b (break and attack) -- default, everyone attacks like normal
* A, a (attack target) -- attack their current targets
* k -- something undocumented, says something about capships. Probably it's an order to take out capship turrets with priority, or it's a pure bomber order to attack capships and ignore fighters.
* F, f (flagship?) -- Ship being escorted. I would imagine that it's an order to attack a ship being escorted by the hostile faction. Alternatively, it could be an order to fly in formation.
* L, l -- undocumented, like F but has complicated formation rules. Could be a shortcut for "Leave" - ships heading out.
* E, e (escort) -- half of this is copy and pasted from L but I have no idea. I'd say it is "escort", escort a designated ship.
* P, p (protect) -- I want to help out

Unfortunately I don't see any codes for acting like a sitting duck... You could try something like making it target itself, or making it target NULL (which you get by calling the constructor VS.Unit() ) and then using something like "A.". Or, just try doing a "B." and having it target you, and make sure it is friendly... then it might just fly near you. I believe you can get the flight group to fly to places by having it target them and then force it to do Unit.setFgDirective("B.") which I think forces it to act like normal and fly to this target.

For some directives to work, you must set the appropriate target and adjust the relation between the factions to either hostile (e.g. attack) or friendly (escort, protect). Here's a snippet to get you started:
<code><pre>
self.aggressor.SetTarget(self.victim)
VS.AdjustRelation(self.aggressor.getFactionName(),self.victim.getFactionName(),-1,-1)
self.aggressor.setFgDirective("A.")
</pre></code>

=See Also=
* [[HowTo:Edit_Missions:Python:Bindings:CPP]]
* [[HowTo:Edit_Missions:Python:Bindings:Python]]

@@ Line 61: / Line 61: @@
 You can also play speech at the same time as displaying the message. To do this you will require an ogg file that you instantiate with the following command:
-<code><pre>VS.playSound("com_questname/speechname.ogg", self.player.Position(), (1,1,1))</pre></code>
+<code><pre>VS.playSoundCockpit("com_questname/speechname.ogg")</pre></code>
 ==News==

@@ Line 1: / Line 1: @@
 =Useful Python Functions=
-Most of the python bindings (to the c++ engine) are listed in <code>data4.x/modules/stub/VS.py</code> and commented in [[HowTo:Edit_Missions:Python:Bindings:Python]].
+Most of the python bindings (to the c++ engine) are listed in <code>data/modules/stub/VS.py</code> and commented in [[HowTo:Edit_Missions:Python:Bindings:Python]].
 There are many other useful functions coded in python and distributed through various other classes.
-* <code>data4.x/modules/Vector.py</code> contains vector manipulation functions
+* <code>data/modules/Vector.py</code> contains vector manipulation functions
-* <code>data4.x/modules/universe.py</code> has functions related to the current and adjacent systems
+* <code>data/modules/universe.py</code> has functions related to the current and adjacent systems
-* <code>data4.x/modules/unit.py</code> provides some unit properties, methods, and actions
+* <code>data/modules/unit.py</code> provides some unit properties, methods, and actions
-* <code>data4.x/modules/launch.py</code> is useful for spawning units in almost any place
+* <code>data/modules/launch.py</code> is useful for spawning units in almost any place
-* <code>data4.x/modules/faction_ships.py</code> allows for a fine creation of ship lists by type and faction, e.g. for spawning.
+* <code>data/modules/faction_ships.py</code> allows for a fine creation of ship lists by type and faction, e.g. for spawning.
 Some of the functions that might be of help when writing quests and adventures are discussed in the following.
@@ Line 57: / Line 57: @@
 Comm animations can be called from your quest script and will be shown on the Comm VDU:
 <code><pre>self.player.commAnimation("com_questname_animationname.ani")</pre></code>
-The animation files must be placed in a corresponding folder <code>data4.x/animations/com_questname_animationname.ani</code> and the animation definition file named equally ''com_questname_animationname.ani''.
+The animation files must be placed in a corresponding folder <code>data/animations/com_questname_animationname.ani</code> and the animation definition file named equally ''com_questname_animationname.ani''.
 You can also play speech at the same time as displaying the message. To do this you will require an ogg file that you instantiate with the following command:

@@ Line 67: / Line 67: @@
 ==News==
-Note that we should eventually make the news reports line up with the quests... :-) I have some ideas how to do that. Basically you can call
+To register news you will need the following python code:
 <pre>
-VS.IOmessage ("game","news","A drone was sighted in the delta prime...blah blah blah")
+import news
 </pre>
-and then people will see it in the game when they click on GNN likewise if you send it to
+and then people will see it in the game when they click on GNN.
 ==More Topics==

@@ Line 19: / Line 19: @@
 * <code>self.planet = unit.getUnitByName('Atlantis')</code> - get planet Atlantis
 * <code>self.station = unit.getUnitByName('MiningBase')</code> - get the mining base
-* <code>self.object = unit.getUnitByName('Jump_To_Nethuuleil')<code> - get the jump point
+* <code>self.object = unit.getUnitByName('Jump_To_Nethuuleil')</code> - get the jump point
 * <code>self.vessel = unit.getUnitByName('Ox')</code> - get an Ox ship
 * <code>self.gf = VS.launch("Charlotte the Harlot","Robin","privateer","unit","default",1,1,(1000,10,3000),'')</code> - creates one ship of type "Robin", being of the faction "privateer", at position (1000,10,3000), which will behave like "default" and show up in the HUD as "Charlotte the Harlot"

@@ Line 45: / Line 45: @@
 You can even set your own color for the messages with a html color code:
-* <code>VS.IOmessage (20,"Oxen","You","#8080FFYou don't remember me?")</code> - prints the comm message in light blue.
+<code><pre>VS.IOmessage (20,"Oxen","You","#8080FFYou don't remember me?")</pre></code>
-** <code>self.txtColor="#8080FF"</code>
+prints the comm message in light blue.
-** <code>VS.IOmessage (30,"Oxen","Privateer",self.txtColor+"I can hardly believe this")</code> - you can even define a color variable and add it to each line.
 As far as the communications go, there is a variable in cockpit that holds what the VDU screen shows as possible options. Unfortunately the communications system is not scriptable at the moment.
 Comm animations can be called from your quest script and will be shown on the Comm VDU:
-* <code>self.player.commAnimation("com_questname_animationname.ani")</code>
+<code><pre>self.player.commAnimation("com_questname_animationname.ani")</pre></code>
 The animation files must be placed in a corresponding folder <code>data4.x/animations/com_questname_animationname.ani</code> and the animation definition file named equally ''com_questname_animationname.ani''.
 ==News==

@@ Line 81: / Line 81: @@
 The following directives are available:
-* H, h (help) -- leader of flightgroup requests help.
+<code><pre>
-* B, b (break and attack) -- default, everyone attacks like normal
+* H, h (help) - "Help me out!" - leader of flightgroup requests help for self.
-* A, a (attack target) -- attack their current targets
+* B, b (break and attack) - default, everyone attacks like normal.
-* k -- something undocumented, says something about capships. Probably it's an order to take out capship turrets with priority, or it's a pure bomber order to attack capships and ignore fighters.
+* A, a (attack target) - attack their current targets.
-* F, f (flagship?) -- Ship being escorted. I would imagine that it's an order to attack a ship being escorted by the hostile faction. Alternatively, it could be an order to fly in formation.
+     // a is now used for AI, for backward compatibility. do not use for player.
-* L, l -- undocumented, like F but has complicated formation rules. Could be a shortcut for "Leave" - ships heading out.
+* K, k - "Attack my target!"
-* E, e (escort) -- half of this is copy and pasted from L but I have no idea. I'd say it is "escort", escort a designated ship.
+* F, f (formation) - "Form on my wing." - it is an order to fly in formation.
-* P, p (protect) -- I want to help out
+* L, l (lalala) - "Get in front of me and prepare to be tractored in."
 Unfortunately I don't see any codes for acting like a sitting duck... You could try something like making it target itself, or making it target NULL (which you get by calling the constructor VS.Unit() ) and then using something like "A.". Or, just try doing a "B." and having it target you, and make sure it is friendly... then it might just fly near you. I believe you can get the flight group to fly to places by having it target them and then force it to do Unit.setFgDirective("B.") which I think forces it to act like normal and fly to this target.