world: wrap sprite index if out-of-bounds

CHANGELOG.md

@@ -11,3 +11,4 @@ Changelog
 * tools: fixed an issue that prevented the data compiler from restoring and saving its state when launched by the Level Editor
 * tools: the game will now be started or stopped accordingly to its running state when launched from the Level Editor
 * tools: the Properties Panel now accepts more sensible numeric ranges
+* world: sprite's frame number now wraps if it is greater than the total number of frames in the sprite

docs/lua_api.rst

@@ -640,6 +640,8 @@ Sprite
 
 **sprite_set_frame** (rw, unit, index)
 	Sets the frame *index* of the sprite.
+	The *index* automatically wraps if it greater than
+	the total number of frames in the sprite.
 
 **sprite_set_visible** (rw, unit, visible)
 	Sets whether the sprite is *visible*.

src/resource/sprite_resource.cpp

@@ -124,10 +124,12 @@ namespace sprite_resource_internal
 		SpriteResource sr;
 		sr.version = RESOURCE_HEADER(RESOURCE_VERSION_SPRITE);
 		sr.obb = obb;
+		sr.num_frames = num_frames;
 		sr.num_verts = num_vertices;
 
 		opts.write(sr.version);
 		opts.write(sr.obb);
+		opts.write(sr.num_frames);
 
 		opts.write(sr.num_verts);
 		for (u32 i = 0; i < array::size(vertices); i++)
@@ -142,6 +144,7 @@ namespace sprite_resource
 {
 	const f32* frame_data(const SpriteResource* sr, u32 i)
 	{
+		CE_ENSURE(i < sr->num_frames);
 		return ((f32*)&sr[1]) + 20*i;
 	}
 

src/resource/sprite_resource.h

@@ -19,6 +19,7 @@ struct SpriteResource
 {
 	u32 version;
 	OBB obb;
+	u32 num_frames;
 	u32 num_verts;
 	// verts[num_verts]
 };

src/resource/types.h

@@ -65,7 +65,7 @@ struct UnitResource;
 #define RESOURCE_VERSION_SHADER           u32(1)
 #define RESOURCE_VERSION_SOUND            u32(1)
 #define RESOURCE_VERSION_SPRITE_ANIMATION u32(1)
-#define RESOURCE_VERSION_SPRITE           u32(1)
+#define RESOURCE_VERSION_SPRITE           u32(2)
 #define RESOURCE_VERSION_TEXTURE          u32(1)
 #define RESOURCE_VERSION_UNIT             u32(1)
 

src/world/render_world.cpp

@@ -429,7 +429,7 @@ void RenderWorld::render(const Matrix4x4& view)
 		// Render sprites
 		for (u32 i = 0; i < sid.first_hidden; ++i)
 		{
-			const f32* frame = sprite_resource::frame_data(sid.resource[i], sid.frame[i]);
+			const f32* frame = sprite_resource::frame_data(sid.resource[i], sid.frame[i] % sid.resource[i]->num_frames);
 
 			f32 u0 = frame[ 3]; // u
 			f32 v0 = frame[ 4]; // v

src/world/render_world.h

@@ -61,6 +61,8 @@ struct RenderWorld
 	void sprite_set_material(UnitId unit, StringId64 id);
 
 	/// Sets the frame @a index of the sprite.
+	/// The @a index automatically wraps if it greater than
+	/// the total number of frames in the sprite.
 	void sprite_set_frame(UnitId unit, u32 index);
 
 	/// Sets whether the sprite is @a visible.