MODDING: The resource system
Every resource that the game uses — images, levels, animation definitions, sprites and tilemaps — are stored together in the "resources" folder. To start modding, you probably want to grab a copy of this folder to make your own changes in. You can right-click the Deathtroid app icon, choose Show Package Contents, and navigate to it through Contents > Resources > resources. Alt-drag it to your desktop to make a copy.
Now that you have your own copy, you want to tell Deathtroid to use YOUR resource folder. When you start Deathtroid, you are presented with our ultra-boring placeholder menu. In the middle, you can choose Resource folder: click the drop-down, "Choose...", and select your own resource folder. This is saved in your settings, so you don't need to do it every time Deathtroid starts.
HOWTO: Make Samus run left
Every resource either HAS a .resource file, or IS a .resource file. For example, samus_run_left.png is a sprite sheet with the animation for running left. Adding this image to the resources folder is not enough to make Deathtroid pick it up: you also need to create a "definition file", a JSON file with the .resource extension. In this case, an Image resource is made by creating samus_run_left.image.resource. You can edit it with any programmer's editor, such as TextMate. The contents of samus_run_left.image.resource is:
{"file":"samus_run_left.png"}
An image can be used by different systems. In ordet for it to be displayable to screen, we also need to create a 'texture' resource, called samus_run_left.texture.resource. Its contents is:
{"image":"samus_run_left.image"}
… essentially just referencing the 'image' file. However, it's still just one big image file, Deathtroid doesn't know of the diferent frames in the image. For this, we need to create a Spritemap file, called samus_run_left.spritemap.resource. Its contents is:
{ "texture": "samus_run_left.texture", "frameCount": 10, "frameSize": [48, 64] }
This resource starts off by referencing another resource — the texture that contains our sprite sheet image. Then we simply define our frame size (the pixel size of a single frame) and the number of frames in the image.
Finally, we need to tell our Samus sprite which animations to play for different states that the Samus entity can be in. These definitions are contained in the samus.animation.resource definition file:
{ "animations" : { "walking-left" : { "size" : [3.0, 4.0], "center" : [1.5, 4.0], "fps" : 15.0, "spriteMap" : "samus_run_left.spritemap" }, "walking-right" : { "size" : [3.0, 4.0], "center" : [1.5, 4.0], "fps" : 15.0, "spriteMap" : "samus_run_right.spritemap" }, ...
One state that Samus can be in is "walking-left". When Samus is in this state, her entity will be 3 tiles wide and 4 tiles high, with a center-of-gravity at (1.5, 4.0) inside the sprite. (This data is not currently used, but will be soon). The animation will be played at 15 frames per second, and will use the different frames in the samus_run_left sprite map.
Tilesets might become their own resources in the future, but right now they are just normal textures. They must be either 64x64 or 128x128 (any square power-of-two will be possible), and each tile is 16x16 pixels.
A "room" is a single room in Metroid. A room has a list of layers (for example a parallax scrolling background layer and a foreground layer), a special collision layer (defining which tiles Samus and other entities can collide with), and a list of entities that will be spawned once a player enters the room. You generally don't need to edit .room.resource files manually, as Deathtroid has a built-in editor for them. That will be the topic of a separate article.