Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The atlas file (with extension .atlas) is produced by Spine. The purpose of an atlas file is to define the coordinates in a PNG file used for different named regions. The atlas file defines both the .png that is used as well as its regions.
By default, atlas files are loaded into the runtime type Spine.Atlas.
You can produce an .atlas file from a FlatRedBall .achx file by using the AchxToSpineAtlas.exe tool.
At the time of this writing you must build this tool yourself. To do this:
Clone the FlatRedBall Repository
Open <FRB Root>\FRBDK\AchxToSpineAtlas\AchxToSpineAtlas.sln
Build the tool which produces a .exe
Once you have built the tool you can use it either in the command line, or you can set up a File Build Tool association.
To run the tool in the command line, run the .exe with two parameters:
The source (.achx) file
The destination (.atlas) file
For example, you can run the tool using the following command to build an .atlas file:
To use the AchxToSpineAtlas.exe tool as a File Build Tool in FlatRedBall:
Open your project in FlatRedBall
Select the Settings -> File Build Tools menu item
Click Add new build tool
Click the ... button to select the BuildTool. Navigate to where AchxToSpineAtlas.exe is located
Set the SourceFileType as achx
(no period before the extension)
Set the DestinationFileType as atlas
After you click the OK button, FlatRedBall understands that .achx files may be used to build .atlas files.
Note that this change now results in FlatRedBall asking you about the build tool whenever you add a new .achx file.
If you are adding a file which you would like to be treated as an AnimationChain, then select the <None> option. For more information on build tools, see the File Build Tools documentation.
The SpineDrawableBatch class is responsible for drawing Spine in your FlatRedBall game. If you have used Tiled in your FlatRedBall projects, you can think of the SpineDrawableBatch as being similar to a Tiled Layer. In other words, the SpineDrawableBatch has the following characteristics:
It can be positioned explicitly, although this is typically done through attachments in generated code
It has a Z value which controls its sorting
It produces a new render break (this may change in the future)
By contrast, normally Tiled maps are added to Screens; however, SpineDrawableBatches are typically added to Entities.
Spine files are needed to draw a SpineDrawableBatch. Conceptually you can think of these files similar to how you might think of a .achx file - it needs to be loaded as part of an entity or screen before it can be used to display any graphics.
To add a SpineDrawableBatch to an entity:
Create an entity that will contain the SpineDrawableBatch. This example uses an Entity called Soldier
Drag+drop a Spine skeleton file (.json) into the Entity's files
Drag+drop an Atlas file (.atlas) into the Entity's files
Drag+drop the matching texture file (.png) into the Entity's files
Select the Skeleton entry in FlatRedBall, click on the Spine tab, and change the Atlas property the desired Atlas file. It should appear in the dropdown.
Important: At the time of this writing, the three files must be loaded in the proper order. The order is:
Texture file (.png)
Atlas (.atlas)
Skeleton (.json)
You can re-order the files by holding down the ALT key on the keyboard and pressing the up and down keys.
This requirement may go away in the future as the Spine plugin gets better at tracking dependencies.
Note that the texture file (.png) is loaded when the atlas is created and ultimately uses a FlatRedBall content manager. This means that if your png is already loaded (such as by being in Global Content Files), then you do not need to also have the png in your entity. This is especially useful if your atlas references a shared sprite sheet which is used by other screens and entities.
Now the Spine files have been added to the entity, we need to add them as an object. By adding an object we can control properties such as position (offset) and scale. Also, each individual object can be independently animated. To add and attach the SpineDrawableBatch:
Drag+drop the skeleton file from Files onto Objects
Change the Source name to Entire File (SpineDrawableBatch)
Enter a name such as SpineDrawableBatch
Click OK
You should now have all three files in your Entity as well as a SpineDrawableBatch in the Objects folder.
To see the entity instance in-game, drag+drop the entity onto a Screen, such as GameScreen. Run the game and the Spine Drawable Batch should appear.
Spine supports events which can be handled in code. Events are defined in Spine which can include parameters of different types such as ints, floats, and strings.
These events can be handled in code by subscribing to a SpineDrawableBatch's Event event, or through the FlatRedBall Editor.
To subscribe to an event in FRB Editor:
Create a SpineDrawableBatch object in your Entity
Drag+drop the SpineDrawableBatch into the Events folder
Change the name if desired, then press OK
The new event can be handled in the Events.cs file of your Entity. For example, if your Entity is named Soldier, the event is in Soldier.Event.cs.
The Event event is can be subscribed to just like any event in C#. To do so, simply use the +=
operator to add a handler to the Event, as shown in the following code snippet:
When a Spine event is raised it may have parameters which are passed. The parameter type can differ per event type, so the Event class that is passed to the handler contains the information.
You can decide the meaning of each paramter in your game. For example, you may decide to award points when a particular event occurs by reading the e.Int
value.
FlatRedBall integrates with the Spine tool using the Spine plugin.
To use Spine in your project, you must do the following high level steps. Each step will be explained in detail below:
Link your game project against FlatRedBall Source
Link your game project against the Spine
Load the Spine shader (.fx) file
You can use Spine purely in code, or you can use Spine in the FlatRedBall Editor by adding the Spine plugin. The FlatRedBall Editor plugin enables adding Spine files (skeleton and atlas) to your FlatRedBall project. The plugin generates code for loading these files.
To use the Spine plugin, you must also install the SpinePlugin .plug file.
Once you have linked your game to FlatRedBall Source, you need to link your game to FlatRedBall.Spine.MonoGame.DesktopGL. As of January 15, 2024, MonoGame DesktopGL is the only platform that supports FlatRedBall.Spine. New platforms will likely be added over time. If you are planning on targeting a new platform, make a request on Discord.
To add FlatRedBall.Spine to your project:
Open your project in Visual Studio
Right-click on your Solution in the Solution Explorer
Select Add -> Existing Project...
Navigate to the folder where you cloned FlatRedBall.Spine and select <FlatRedBall.Spine Root>/Source/FlatRedBall.Spine.MonoGame.DesktopGL.csproj
Link FlatRedBall.Spine.MonoGame.DesktopGL in your game project's dependencies.
Your project should now link to FlatRedBall.Spine.MonoGame.DesktopGL.csproj.
Although it is not necessary, using the FlatRedBall.Spine plugin is recommended as it can reduce the amount of code necessary to work with Spine. To install the FlatRedBall.Spine plugin:
Select Plugin->Install Plugin in FlatRedBall
Use the ... button to locate and select the SpinePlugin.plug file, then click OK
Restart FlatRedBall
Once you have restarted FlatRedBall, you should see Spine listed in the installed plugin. Select Plugins -> Manage Plugins, and scroll down to make sure the plugin has installed.
Alternatively you can clone the Spine plugin if you prefer to build from source and diagnose problems. To do this:
Open SpinePlugin/SpinePlugin.sln
Build->Rebuild the plugin
The latest plugin .dll will be built and also copied over to the Glue output folder.
The SpineShader is required to render Spine. To load the Spine Shader:
Add the SpineEffect.fx file to GlobalContent by drag+dropping the file into your Global Content Files folder in FlatRedBall
Open Game1.cs and add the following code in Initialize after GeneratedInitialize();
:
You must own a license to Spine to use this in your project. For more information see the Spine runtimes license here:
The first step is to link your FlatRedBall project to source. To link your game to FlatRedBall Source, see the .
Clone the repository for FlatRedBall.Spine
Download the SpinePlugin.plug file from the Releases page
Clone the FlatRedBall.Spine repository . If you clone both FRB and this repository to the same root Github location, then the file links will work correctly
Download SpineEffect.fx file from the Releases page
The Skeleton property gives you full access to the underlying Spine object. Simple games can work directly with the SpineDrawableBatch, but more complex games may require directly reading from or manipulating the Skeleton object.
For information about working directly with the Skeleton object, see the Runtime Skeleton documentation on Spine's website.
The SetCollision function can be used to assign/update collision on an ICollidable through its ShapeCollection. In other words, this method allows the creation of collision through the Spine tool which can be used to create CollisionRelationships, or to perform manual collision checks.
Keep in mind that you are not required to define collision in a Spine file. If your game works well without the precise collision offered by Spine bounding boxes, then you can add shapes such as AxisAlignedRectangles and Circles to your entity.
Spine has support for bounding boxes - which conceptually correspond to FlatRedBall Polygons.
These bounding boxes can be converted to FlatRedBall Polygons which can be used in your project. These polygons are fully-featured, just like polygons created either in the FRB Editor or in code. In other words, these polygons have the following characteristics:
They are attached to the Entity, so solid (move/bounce) collision will result in the entity being repositioned and have its velocity changed according to the physics applied.
They can be added to the Entity's Collision ShapeCollection so they can be used in collision relationships.
They are named and can be exposed in the FRB Editor so that CollisionRelationships with subcollisions can reference them
Furthermore, polygons from Spine have the following features and characteristics:
Polygons can be defined in the FRB Editor to match the names of the polygons, or they can be created at runtime without a corresponding FRB Editor entry
Polygons respond to animations, so if a SpineDrawableBatch changes its rotation or scale, the FlatRedBall Polygon automatically adjusts
To use SpineDrawableBatch collisions, the SetCollision method needs to be called every frame. Typically this is called in the CustomActivity (or derived method) inside an entity which implements ICollidable as shown in the following code snippet:
This method updates the polygons in the argument ShapeCollection (this.Collision
) every frame. The code checks for name matches between the bounding box in Spine and the name of the FlatRedBall Polygon in the ShapeCollection. If a match is found, then the FlatRedBall Polygon is updated to match the Spine object. If a match is not found, then a new FlatRedBall Polygon is created if the last argument (createMissingShapes) is true
.
Typically, if you would like to define the collision in Spine without creating anything in the FlatRedBall Editor, then you can pass true
as the final parameter. In this case, the Objects folder would not contain any FlatRedBall Polygons, and every bounding box in the Spine object would be used in collision relationships.
By contrast if you would like to assign custom collision per-shape (such as by using CollisionRelationship subcollisions), you can define a polygon in the FlatRedBall Editor. You do not need to create the points on the newly-created Polygon in the FlatRedBall Editor since they will be updated every frame by the SetCollision call. The only requirement is that the Polygon that you create has a name that matches one of the bounding boxes in your Spine file.
In this case, the Polygon will automatically be added to the Collision ShapeCollection, and it will be modified by the SetCollision call every frame.
Note that the Polygon must be part of the Collision ShapeCollection. In other words, IncludeInICollidable must remain true, which is the default. If you set this to false in FlatRedBall, then the SetCollision
method will not find this Polygon.
You are free to define as many or as few Polygons as you would like in FlatRedBall. If you define them, then SetCollision will update them. If you do not define them, then SetCollision will either add them (if true
is passed as for createMissingShapes), or they will be completely ignored. Whether you define them, and whether you pass true or false for the createMissingShapes parameter depends on how much explicit control you would like over the definition of your polygons.