Clone wiki

trosnoth / Adding an Upgrade

Adding an Upgrade

Trosnoth upgrades are defined in trosnoth/model/upgrades.py. Each upgrade is represented a subclass of Upgrade. To define a new upgrade:

  1. Create a subclass of Upgrade.
  2. Make sure you apply the @registerUpgrade decorator to your upgrade class.
  3. Set upgradeType to a single byte that will be uniquely used to represent this upgrade when communicating over the network. (See below for a list of upgrades and their codes.)
  4. Set requiredStars (cost) and timeRemaining (duration)
  5. Set name to the name that should be used for this upgrade in the UI.
  6. Set action to a unique string to be used in the UI event system for this upgrade (we generally just use the upgrade name in lower case).
  7. Set order to a number that's used to determine the ordering of upgrades when listed in the UI.
  8. Set defaultKey to the key that should be used to select this upgrade, or leave it as None for no keyboard shortcut.
  9. Set iconPath to the name of the icon image file, within trosnoth/data/sprites.
  10. Read the section on server and client timing below, and decide whether your upgrade needs the doNotWaitForServer flag to be set.
  11. Write the upgrade code (see section below).

Server and client timing

For most upgrades, when a player requests the upgrade, there's a short delay while the message is sent to the server, which responds to confirm that the upgrade can be purchased. This is by far the simplest way for an upgrade to operate, and usually, this short delay is allowable. If this delay is ok for your upgrade, then you don't have to do anything special.

In rare cases (e.g. when firing a grenade), the exact position of the player when they purchased the upgrade is important. For these upgrades, a flag can be set on the class, doNotWaitForServer = True. If this flag is set, then if the client thinks that the upgrade can be purchased, it goes ahead on that assumption. Then, once the server has double-checked and replied, either upgrade.serverVerified() or upgrade.deniedByServer() will be called on the client. If you are writing this kind of upgrade, make sure you think about what to do in the deniedByServer() case. This can happen if other players on your team use your team's stars before your request reaches the server.

Writing upgrade code

Writing the upgrade code will be different depending on what your upgrade does. You may need to:

  • Write code that happens when the upgrade is used. The simplest way to do this is to override one or more of the following methods:

    • use(): this is called when the upgrade is used (after the server confirms that's ok)
    • timeIsUp(): use this to perform a specific action when the upgrade timer runs out (e.g. explode the grenade)
    • delete(): called when the upgrade stops for any reason (e.g. time runs out, or user cancels it). You can override this method to undo things that you did in use(). But don't forget to call the super() method or the upgrade won't actually be deleted.
  • Modify some of the game logic (e.g. in universe.py or player.py) to respond to the fact that the player has an upgrade. You can check if the player has your upgrade using isinstance(player.upgrade, MyUpgradeClass), or player.upgrade is not None and player.upgrade.upgradeType == MyUpgradeClass.upgradeType.

  • Update the UI to show the upgrade. The code to look at for this will be under trosnoth/trosnothgui/ingame/. Generally, start looking in viewManager.py, then maybe sprites.py and universegui.py.

Existing Upgrades

The following list contains current upgrades and their codes. Those marked as (special) cannot be used in the game unless the server has specifically enabled them.

  • Shield: 's'
  • Phase shift: 'h' (special)
  • Turret: 't' (special)
  • Minimap disruption: 'm'
  • Grenade: 'g'
  • Ricochet: 'r'
  • Ninja: 'n'
  • Shoxwave: 'w'
  • Machine gun: 'x'
  • Bomber: 'b'
  • Respawn freezer: 'f' (special)
  • Directatorship: 'd' (special)

See Also

Updated