Starward Rogue:XML - Overall Organization

Formatting

If you can, please use an editor like Visual C# 2008 or similar that will do tab indenting in such a way that matches what Chris and Keith are checking in from Visual Studio 2008. We don’t want to have a formatting war accidentally happening in SVN. ;)

Overall Organization

There are a few key words that are important to understand for purposes of the API documentation.

GameEntity

• This is most things in the game. But, specifically:
• GameEntityCategory.Shot
  • These are actual individual bullets moving around. They might be part of some larger pattern or who knows, but the important thing is that this is one bullet moving around.
• GameEntityCategory.Ship
  • Good or bad, this is either a player or an enemy.
  • Ships CANNOT attack directly. They have to have guns mounted on them (see below), and then the guns do the attacking.
    • If a ship looks like it has no gun, it is using an invisible gun.
• GameEntityCategory.ItemPickup
  • These are actual item pickups that you can step on and pick up. You can also drop these.
  • If you are doing item design, probably this is where you will do that.
• GameEntityCategory.Obstacle
  • This is a very strange category and likely you won’t do much with. These include things ranging from mines to interior walls to those floor-mounted lasers to the shootable and bombable wall bits, etc.

EntitySystem

• These are things that do stuff when mounted on a ship. Usually that means shoot something, but it could also be a system for healing or who knows what.
• Typically when an item is picked up by a player, it’s going to add a new system to the ship of the player, and/or remove some. Well, maybe half the time. That leads into...

EntityModifier

• These are not things that you can define directly, unlike all the things above. But they’re so central that I’m going to go ahead and mention them here. You will be asking us for new modifiers all the time, and we’ll code them and then you can use them, so it’s not like these aren’t relevant for you.
• A modifier can be applied either to a system or to a ship, and it causes some sort of behavioral change or other effect. These might last for a little while or forever.
• For example these might cause the bullets from that one system to ricochet from now on, or might cause all bullets from all systems on the ship to move past non-wall obstacles for the next 30 seconds.

PeriodicMovementMode

• This is another thing that you can’t define directly, but again is super central and something you’ll be asking us for now and then. These are things that you’ll attach to various enemies to make them behave in very specialized ways for a little while.
• For example they might do an “insane through-wall charge,” or a “shadow dash,” or a “freakout.” We’ll be adding to this list with time.

BulletPattern

• This is incredibly important and something that is not to be confused with shots. A bullet pattern is basically defining scripted behavior in a SHMUP-like fashion for one bullet that comes out of a system of a ship.
• The original bullet typically dies immediately on being fired, but spawns a bunch of other bullets that then do a bunch of other insane stuff, which might include spawning yet more bullets.
• I’m using the word shot and bullet interchangeably here, but the actual word in code is shot.

BulletPatternVariables

• These are not actually a game thing, but rather are a convenient way for setting up far-more-complex bullet patterns without having to repeat large sections of code repeatedly.
• An individual bullet pattern variable is something that does the bulk of the logic for a bullet pattern, but it can take in variables that you define, and one bullet pattern can call the same variable multiple times with different arguments each time, or multiple bullet patterns can call the same variable with different arguments and get hugely different results.
• Individual variables can even call other sub-variables in order to avoid duplicate code.
• Basically: if you find yourself copy-pasting a large amount of bullet code that will be largely identical except for some numbers here and there, then you’re doing it wrong. ;)
  • You need to make one bullet variable that contains that block of code, insert variables for those numbers you want to have vary, and then call the variable with those numbers passed in differently each time.
  • Why do this? It’s easier to read, for one. It’s also easier for you to fix bugs or make other tweaks in, so it saves you time. It’s quicker to type out in the first place, once you’re used to it.
• If you’re a programmer, you may note that the word “variable” is actually kind of inappropriate here. These “variables” are actually a bit more like methods or functions at this point, to be honest. They started out more variable-like, sorry about that.

FloorGeneration

• There’s some various stuff in here relating to how dungeon floors get created.

Image Folders

A lot of this stuff uses images, of course. There are a few things to explain about these folders:

• RuntimeData/Images/Items
  • Anything that is an ItemPickup will have an image in here.
  • Subfolders are arbitrary, and are defined just for organizational purposes.
  • Chris will be the one defining most of the actual images in here, so if you are making a new item pickup that doesn’t yet have an image, you can just reference some other item image temporarily.
• RuntimeData/Images/Ships
  • Anything that is a Ship goes in here.
  • Subfolders are arbitrary, and are defined just for organizational purposes.
  • Chris will be the one defining most of the actual images in here, so if you are making a new ship that doesn’t yet have an image, you can just reference some other item image temporarily.
    • THAT said, if you are making a variant of a ship that combines a base with some other attachments that already exist but not in the combination you want to use them, then you can do that. That won’t actually require you adding any new images, but you would want to look in these folders and see what’s available to you.
• RuntimeData/Images/Shots
  • If you want to see what the various shot shapes are, this is where you come look. It’s a really good idea to do so that you can properly design bullet patterns -- or even individual gun shots -- that “feel right.”
• RuntimeData/Images/Systems
  • Any entity systems that are defined will be referencing someting in here. Either that will be a visible turret or other attachment, OR it will be referencing “Invisible,” which is a tiny transparent image. A lot of systems will do that.
  • Subfolders are arbitrary, and are defined just for organizational purposes.

XML Folders

This is where anything you define actually goes.

It is important to note that enemies and systems and shots and all that sort of thing are ENTIRELY data-driven, unlike in our other games. That makes this incredibly modder-friendly, as well as easy for us to define without having to re-code things.

Some things, like behaviors or modifiers, are of course not defined in data. Those are defined in code, but in such a way that you can then use them in a huge number of ways and combinations in your xml files. If you’re a programmer, think of the xml files as being your “program,” while the things we put in hardcoded definitions are the “language” and “libraries” that you use.

ABOUT FOLDERS!

• The folder definitions are not arbitrary, and are not just for organization.
• The game looks at each folder as a “type of thing,” and then reads in any xml files it finds within there.
  • This is very modder-friendly as well, because it means that there can be any number of arbitrary xml files in there and the game will read them all. This means that a modder’s additions won’t be accidentally overwritten next time we push a release to the game, for instance.
  • This also makes it so that individual staff members can have individual files of their own in each folder that have a prefix that is either their name, initials, forum handle, or whatever.
    • For instance, all of Misery’s stuff has Misery_ in front of it, and Chris uses CMP_ in front of it. Stuff that Keith is adding for test purposes also just goes in the CMP_ files, because why not.
  • Even though the filenames are completely arbitrary and the only thing that matters is what folder it is in, it’s a great idea to use a format that includes the name of the folder after your name/initials/whatever, so that in an xml editor we can tell what the file is -- opening these as tabs in visual studio won’t let us see what folder they came from, for instance; we can only see the filenames.
• Lastly, when it comes to specific files that are being created by staff, bear in mind that Chris in particular may go in and make tweaks in the files of other people, or even make additions.
  • Thanks to the wonderful diffing capabilities of SVN, you can easily see what he changed, and the changes he made and that you make will all be able to merge very easily unless you both changed exactly the same line. In which case SVN has tools for reconciling those changes, too.
  • If you have specific proposals for changes to the enemy or other design of someone else, then feel free to make changes in someone else’s file, too. If you commit something like that and the other person or Chris isn’t too fond of it, then that’s something that can always be altered.
    • We have a full revision history, so when in doubt feel free to be liberal about your changes since you can’t permanently break anything.
    • If you are making changes to someone else’s work, though, please make some notes in the svn log as to why -- it’s just good form to explain your commits in general, unless you’re just checking in a batch of images or something.

The Specific Folders

• RuntimeData/Configuration/BulletPattern
  • This is where the bullet pattens go.
• RuntimeData/Configuration/BulletPatternVariables
  • Shockingly, this is the bullet pattern variables.
• RuntimeData/Configuration/EntitySystem
  • In another great twist, all the entity systems are here.
• RuntimeData/Configuration/FloorGeneration
  • Floor generation stuff.
• RuntimeData/Configuration/GameEntity
  • ALL of the game entity stuff is in here.
  • The names and organization is arbitrary, but there are multiple files even just for Chris so that things could be broken out somewhat. Keeping the player hulls away from the familiars away from the enemy ships, etc.
  • If you wanted to have separate files for large enemies, small ones, stationary ones, boss ones, whatever, you can do so.

Starward Rogue XML Documentation Main