Transcendence Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
Modding stations is quite simple.

One thing to be aware of is that there are many different types of stations, and they each have slightly different formats. There is no way to write down every type of station possible, so we will just detail the elements a station can contain, write up some tips and gotcha's, and let you, the modder, decide what your station should be like.

As always one of the best references is the vanilla source, where there are tons of stations defined. Unpack the source and have a look. Use an editor that can search an entire directory (eg. Notepad++) and study the xml. There are many mods on Xelerus that use stations. Have a look there, and you may learn many interesting things. And final point of reference is **always** Transcendence itself. Build the xml, load up the xml and test it. If it runs, good, if not, debug it, and share your knowledge.

**Remember to edit this post if you possess any additional information.**

I will start with laying out the skeleton of a station, and then describe the elements briefly. Note, this is a very basic and boring station, and definitely not the only simple station you can make.

(lines prefixed with ;; are comments)

===== Skeleton =====
<code lisp>
;; All objects must have a UNID, stations are no different
<StationType UNID="&stDemoStation;"
    ;; The name of the station as it will appear to all.
    ;; Can be any string, just don't make it too long
    ;; (it most times has to fit on the top of a DockScreen)
    name="Demo Station"

    ;; In this case we want a Dockscreen, so we name it here.
    ;; Notice how we use Main a bit later as the name of the DockScreen.
    ;; This can be any string, as long as it is used later.
    ;; You can also reference external Screens by their UNID
    dockScreen="Main"

    ;; If you want to Dock at the station you will have to assign
    ;; some dockingports. If you have a screen defined but no ports
    ;; or vice versa, you will get errors.
    dockingPorts="4"
    >

    ;; a standard image resource. Can be any image you have set up yourself.
    ;; (just like you would for a ship)
    <Image imageID="&rsStations1;" imageX="128" imageY="668" imageWidth="28" imageHeight="28"/>

    <DockScreens>

        ;; The dockscreen we defined above. Making Dockscreens is another topic
        ;; so i wont be covering that here at all

        <Main name="Station DockScreen">
            <Panes>
                <Default desc="You are docked at a Demo Station">
                    <Actions>
                        <Action name="Exit" key="X" default="1" cancel="1" >
                            <Exit/>
                        </Action>
                    </Actions>
                </Default>
            </Panes>
        </Main>
    </DockScreens>

    ;; here we define the ports that we want on the station. the 'x' and 'y' attributes
    ;; define where the ship will dock relative to the center of the station. Getting these
    ;; values right takes a bit of fiddling, and is mostly trial and error.
    <DockingPorts>
        <Port x="45"y="140" />
        <Port x="50"y="-140" />
        <Port x="-50"y="-140" />
        <Port x="-40"y="140" />
    </DockingPorts>

</StationType>
</code>
Ok, that't a very basic uninterresting station, that wont occur anywhere in game, and cant
really do anything. You can put it in a mod though, and load it up and then spawn the station
via script and dock with it, and everything will be as expected.
=====Attributes=====

Here are some more attributes you can set on a station. Some of them i know what do, some of
them i am not sure... Information here will be updated as we leaarn more

<code lisp>
;; yaddayadda
<StationType UNID="&stDemoStation;"

    ;; the sovereign this station will belong to.
    sovereign="&svIndependent;"

    ;; the level of the station
    level="6"

    ;; a set of attributes that define the station. Useful for
    ;; querying via script.
    attributes="populated,friendly"

    ;; the screen the player will be shown if they dock with a destroyed station
    abandonedScreen="TempleDestroyed"

    ;; if the station has a weapon and this set to true, it will
    ;; attack enemies of it's sovereign
    canAttack="true"

    ;; This represents adjustments to the equipped weapons fire rate.
    ;; numbers lower than 10 increase the rate, while numbers over slow it down
    fireRateAdj="10"

    ;; well, hp... Im not 100% sure how these affect the station.
    hitPoints=        "175"
    maxHitPoints=        "100000"
    maxStructuralHitPoints=     "25"

    ;; not 100% sure of the effects of this
    repairRate=         "1"

    ;; this makes the station more resistant to light weapons. It will take some real WMD to hurt it.
    multiHull="true"

    ;; makes the station indestructible.
    immutable="true"

    ;; if this is false, the stations name will be visible on the map.
    noMapLabel="true"

    ;; if this is false, the station will be visible as a green dot on the map.
    noMapIcon="false"

    ;; removes the "a" or "the" from a station's name. (or does not add it)
    noArticle="true"

    ;; the station's name will be "the DemoStation" instead of "a DemoStation"
    definiteArticle="true"

    ;; i am not 100% sure what this does.
    ;; scale="world" makes objects impossible to target, and makes them appear on the
    ;; map as background objects, with no name label (eg. like planets do). They are in
    ;; addition also rendered indestructible. Other possible values are "ship" and "star"
    scale="world"

    ;; as far as i remember this makes bullets pass through the station.
    backgroundObject="true"

    ;; only relevant for stargates, but defines the effect that is triggered when 'G' is pressed.
    gateEffect="&efStargateOut;"

    ;; Writes the name of the station on the screen, next to the station.
    ;; In game only used for the sigs near stargates,
    ;; but handy for making... well... signs!
    sign="true"

    ;; makes the station into a barrier object that ships can't pass through.
    barrier="true"

    ;; the effect to show when a barrier is hit by a ship.
    barrierEffect=      "&efBattleArenaWallHit;"

    ;; this makes the station be able to shoot through friendly targets to hit
    ;; the enemy on the other side.
    ;; See: penintent stations, outlaw turrets, sung satellites, teraton defenders, ares turrets
    noFriendlyFire="true"

    ;; the mass of the station.
    ;; This affects how much force it takes to move the station,
    ;; if it is movable at all (eg. movable="true")
    mass="50000"

    ;; the armor the station is equipped with.
    ;; it has no effect on the final hp of the station, but
    ;; provides the station with the properties of that armor.
    ;; eg. LaserReflect etc...
    armorID="&itLightTitaniumPlate;"

    ;; a beacon will reveal any stations that are close to it (within 10 ls I
    ;; think...) without you having to go near but does not reveal
    ;; the station that the beacon is on.
    beacon="true"

    ;; whether the station is mobile. An example of this is shipwrecks
    ;; (that's right, shipwrecks are stations... go figure!!).
    mobile="true"

    ;; as far as i know this is the small things that come flying off an
    ;; object when you shoot at it.
    ejectaType="&vtWreckEjecta;"

    ;; what happens when this station goes boom?
    explosionType="&vtThermoExplosion3;"

    ;; defines whether your station will get any visitors... umm, i mean
    ;; defines whether your station will be radioactive.
    radioactive="true"

    ;; the station is destroyed when it has no more items.
    ;; used in the floating cargo crates you see around.
    destroyWhenEmpty="true"

    ;; the unique tag will make sure that the station is unique
    ;; either in the system or in the universe. Note that if you
    ;; spawn a station by script and it is not unique, a nasty
    ;; error will be printed to the user.
    ;; possible values are, "inSystem" or "inUniverse"/"True"
    unique=         "inSystem"

    ;; this is used when creating system topology
    ;; It is basically the same as a item levelFrequency string,
    ;; defining at which levels a station can appear, and with
    ;; what frequencies.
    levelFrequency="ucccu rrvv- ----- ----- -----"

    ;; As above, used for system creation. This is used to define which
    ;; surrounding this station requires.
    locationCriteria="-planetary"

    ;; end of StationType
    >
</code>
Now, many of the above attributes are mutually exclusive and may crash your game,
so it will take some fiddling to get it all together. The possible combinations
are too many for me to begin to compile a list here, so it will take some experimentation
on the modders part.

=====Elements=====

Apart from attributes, a station can have alot of different elements. I will go over some of
them here.
====Trade====
<code lisp>
<Trade currency="credit" creditConversion="100" max="50000" replenish="5000">
    <Sell criteria="*NU -ID; -NotForSale;" priceAdj="200"/>
    <Buy criteria="*NU -ID; -NotForSale;" priceAdj="50" />
    <Buy criteria="*DU -ID;" priceAdj="10"/>
    <Buy criteria="*NU" item="&itBiofactorPaste;" priceAdj="150"/>
</Trade>
</code>
The <Trade> element defines how this station will buy/sell items.

You can have multiple <Sell> and <Buy> tags with different criteria, to make a station pay more for illegal goods for example.
  * currency
can be either 'credits' or 'rins' and is self explanatory.

  * `creditConversion`
determines how the station handles credits.  If you buy an item for 5000 credits and creditConversion=100, the station's balance will be increased by 5000 credits. (pretty obvious).  If creditConversion=0 and you buy that same 5000 cred item, the station's balance will be reduced by 5000 creds thus limiting the amount of items the player can buy from the station while allowing the player to sell as much as they want to the station.  Tis does not affect the price the player sees either for buy or sell, only how the station handles their side of the finances.
  * `max`
how many credits the station has available. It wont be able to pay more for an object than this.
  * `replenish`
how fast the station regains credits. This amount is added to the station's balance every 12500 ticks or 6.66 minutes.

The <Trade> element can be overriden using gMargin.
<code lisp>
	<Action name="Buy items" default="1" key="B">
		(block Nil
			(setq gPrevScreen "Main")
			(setq gPrevPane "Exchange")
			(setq gMargin intTeratonBuyMargin) ;; intTeratonBuyMargin is a function defined in Teratons.xml
			(scrShowScreen gScreen "&dsRingerBuy;")
			)
	</Action>
</code>
gMargin must be set in the dockscreen prior to entering the buy or sell dockscreen and must be a global function.  This method offers 
a much MUCH more detailed method of setting prices as the function can be as simple or complex as you choose.  You can have the station 
offer a discount if the player has done missions for Korolov, or will pay much less for items that are abundant in the current system.

====Items====
<code lisp>
<Items>
    <Itemcount="1d12"item="&itEuropanIceVodka;" />
    <Table>
        <Nullchance="20"/>
        <Lookup chance="80" count="1d3" table="&trConsumables1;"/>
    </Table>
    <Table count="2">
        <Lookup chance="40" count="1"table="&trMajorItem2;"/>
        <Lookup chance="60" count="1"table="&trMajorItem3;"/>
    </Table>
</Items>
</code>
This defines what items the station will have onboard.
The <Item> tag is similar to the one used on ships.

====ImageVariants====
<code lisp>
<ImageVariants>
    <ImageimageID="&rsBarricades;" imageX="0" imageY="0"   imageWidth="80" imageHeight="80" />
    <ImageimageID="&rsBarricades;" imageX="0" imageY="80"  imageWidth="80" imageHeight="80" />
</ImageVariants>
</code>
This defines a station that has multiple image variants. Each <Image> can refer to any image resource you
have set up, and when the station is spawned you can set which variant the individual station will use.
In game this is used for barricades and barriers. You can also change the variant in game through script
using the (staSetImageVariant) function. This can create some very cool effects where the station changes based 
on some event.

====Devices====
<code lisp>
<Devices>
    <Device deviceID="&itMarkIIIHowitzer;"omnidirectional="true" posAngle="60"  posRadius="85"/>
    <Device deviceID="&itMarkIIIHowitzer;"omnidirectional="true" posAngle="330" posRadius="110"/>
</Devices>
</code>
This defines the items that are installed on the station. Mostly weapons make sense

//Expand on the <Device> element?//

====Ships====
<code lisp>
<Ships>
    <Ship count="1d2"class="&scHurinDestroyer;"orders="patrol" patrolDist="40"/>
        <Escorts>
           <Ship count="1d4+2" class="&scRoninC;" orders="escort"/>
        </Escorts>
	<Table count="1d4">
		<Ship chance="50" count="1" class="&scEI100;" orders="gateOnThreat"/>
		<Ship chance="40" count="1" class="&scBorer;" orders="gateOnThreat"/>
		<Ship chance="10" count="1" class="&scRoninC;" orders="guard"/>
        </Table>
</Ships>
</code>
The ships that this station comes with.
In this example, the station will have 1 Hurin Destroyer patrolling around the station at a distance of 40 lightseconds and 2-6 RoninC ships escorting it.  There will also be 1-4 other ships docked with the station.  A 50% chance of an EI100 that will run away if the station is attacked, a 40% chance that one of those 1-4 ships will be a Borer ship that will also run, and a 10% chance that a Ronin C will appear but if it is present it will attack enemy ships if they get too close to the station.

//Expand on the <Ship> element?//

====Reinforcements====
<code lisp>
<Reinforcements minShips="1">
    <Ship count="1d2"class="&scHurinDestroyer;"orders="patrol" patrolDist="40"/>
</Reinforcements>
</code>
The ships that this station can call as reinforcements.

//Expand on the <Ship> element?//

====Satellites====
<code lisp>
  <Satellites>
	<Orbitals distance="7" angle="45">
		<Station type="&stCommonwealthTurret;" imageVariant="2"/>
	</Orbitals>

	<Orbitals distance="7" angle="135">
		<Station type="&stCommonwealthTurret;" imageVariant="1"/>
	</Orbitals>

	<Orbitals distance="7" angle="225">
		<Station type="&stCommonwealthTurret;" imageVariant="0"/>
	</Orbitals>

	<Orbitals distance="7" angle="315">
		<Station type="&stCommonwealthTurret;" imageVariant="3"/>
	</Orbitals>
  </Satellites>
</code>
A station can have other stations surrounding it, these are known as satellites.  In this example (taken from the CommonWealth Colony Armed station) will place 4 Commonwealth Turrets around the station.  The cargo containers around the Korolov Stations and the annoying walls around the small sung stations are examples of station satellites.

====Encounters====
<code lisp>
<Encounters frequency="uncommon">
    <Ship count="1" class="&scHurinDestroyer;" orders="wander" maxShips="4"/>
</Encounters>
</code>
This adds extra encounters to a system where this station is present.

//Expand on the <Ship> element?//

====Names====
<code lisp>
<Names>NavBeacon %s-%0%0%0</Names>
</code>
Or...
<code lisp>
<Names>DemoStation1; DemoStation2; SomeOtherStationName</Names>
</code>

Provides a list of names from which the actual name of the station will be chosen.

In the first example, %s is replaced with the current systems name,
%0 is substituted by a random number from 0-9, so %0%0%0 could be any number from 000-999.

====StaticData====
<code lisp>
<StaticData>
    <MyVariable>my string of data</MyVariable>
</StaticData>
</code>
Static data is useful for storing all kinds of information on an object that can then
be retrieved later through script. You can have any amount of <MyVariable> tags inside 
the staticdata element.

Static data can also contain script elements, which can be run later. This is a common way of storing mission scripts and similar

====Events====
<code lisp>
    <Events>
         <OnCreate>
              (sysAddObjRecurringTimerEvent (random 250 500) gSource "Bark")
         </OnCreate>
         <Bark>
             (plyMessage gPlayer "Come to "(objGetName gSource)" for the best prices in the galaxy!!")
         </Bark>
         <OnDestroy>
              (sysCancelTimerEvent gSource "Bark")
         </OnDestroy>
    </Events>
</code>
Events can be a powerful tool in stations.  This set of events will start when the station is first created, and every 250-500 ticks will display a message on your screen that says "Come to (MyStationsName) for the best prices in the galaxy!!" until the station is destroyed.  Events can also be used to control ships for missions, or generate new inventory in the station, scan the system for items or ships.  The Events can do just about anything you can write in code.  Be careful how many recurring events you use in stations as they can eat up your system resources and slow down your game if too many events are firing too often.

=====Georges Notes=====

These are some notes taken from Transcendence.xml on the vanilla stations attributes

<code>
STATION ATTRIBUTES

anarchists:         anarchists
commonwealth:       commonwealth station
commonFleet:        Commonwealth Fleet
commonMilitary:     either Commonwealth militia or Commonwealth Fleet
enemy:              enemy of the player
friendly:           friend of the player
populated:          not an automated station
primary:            main station in the system

ENVIRONMENT ATTRIBUTES

envEarthstation found in earth systems
envFirestation found in fire systems
envWaterstation found in water systems
envAirstation found in air systems

For example, in asteroid systems (+envEarth) any station that
DOES NOT have the envEarth attribute is half as likely to appear
in the system.

Each of the above attributes also has a pair of the form envAvoidsXXX. For
example, envAvoidsAir means that the station is less likely than average to
be found in an ice system.

LOCATION CRITERIA

+planetarystation twice as likely to appear near a planet
</code>

=====Example Mods=====
//feel free to add interesting station mods here//

Here are some mods from xelerus that use stations alot and
might be interesting to look at when modding stations

  * [[http://xelerus.de/index.php?s=mod&id=413|Prophet's Player Stations]]
  * [[http://xelerus.de/index.php?s=mod&id=234|Betel's Storage Station]]

=====Credits=====
Thanks to the following forum users for providing information:

//DarthSaber, Bobby, Prophet, 12Ghost12//

=====Comments=====
//Please place your comments here//

* 05/25/09 - added <Events> section, changed/updated some items that were sketchy after some testing (creditConversion & resupply), expanded ships attribute, <Trade> section and added notes on gMargin.  Added <Satellites>.
Hope this helps! -Prophet


* 05/28/09: I'm not sure the segment on gMargin belongs here. Although it is an interesting function, it has more to do with DockScreens. IIRC it cannot modify that much about the <Trade> section. Eg. it cannot make the station buy or sell items not specified in the xml and it cannot change creditConversion or the other properties. I might be wrong though. -alterecco