Advanced Animation Using Sprites先進的動畫使用精靈
What are Sprite Sheets?精靈是什麼表？
Sprite sheets are 2D animations packed as multiple frames into a single texture image. This allows a much more efficient use of texture memory, which is highly limited on mobile devices, and also minimizes loading time.
精靈表是二維動畫包裝成多個幀到一個單一的紋理圖像。這使得更有效地利用紋理內存，這是非常有限的移動設備，並最大限度地減少加載時間。
Corona supports two types of sprite sheets: those whose animation frames are all sized and positioned uniformly, and those whose frames have non-uniform sizes and positions. In the former case, you simply provide Corona with the width and height of each frame in the sprite sheet image file to create a new internal representation of the sprite sheet. The image below (from the JungleScene sample project that ships with Corona SDK) is an example of a sprite sheet with uniformly-sized frames.
Corona支持兩種類型的精靈表：那些動畫幀大小和位置都均勻，那些畫面有非均勻的的大小和位置。在前一種情況下，您只需提供Corona的寬度和高度每幀圖像中的精靈表文件來創建一個新的內部表示的Sprite表。下面的圖片（從 JungleScene示例項目，船舶與Corona SDK）是一個例子，一個精靈片均勻大小的幀。
In the other case, the positions and sizes of individual frames within the sprite sheet are described by an external data file that can be exported from several sprite sheet generator tools (such as Zwoptex or TexturePacker).
在其他情況下，個別位置和大小框架內的精靈表，描述了一個外部數據文件，可以從幾個精靈出口表發生器工具（如Zwoptex或TexturePacker）。
Corona lets you easily create an internal sprite sheet object from a sprite sheet image and its accompanying data file. See below for examples of how to work with both types of sprite sheets. The sprite sheet below (from the HorseAnimation sample project) contains frames with non-uniform sizes and positions.
Corona讓您輕鬆創建一個內部精靈表對象從一個精靈張圖像和與之配套的數據文件。見下面的例子，如何使用這兩種類型的精靈表。 精靈的表如下（從 HorseAnimation樣本項目）包含框架與非均勻大小和位置。
Corona also includes constructors for complex animated characters with multiple sequences, and sequence playback methods that are time-based rather than frame-based, so animation duration will remain consistent on slower devices. These time-based sequences also allow you to individually choose and tweak the frame rate for each sequence, rather than having the animation speed locked to the application’s global frame rate.
Corona還包括構造複雜的動畫人物與多個序列，序列回放方法是基於時間，而不是基於幀的，因此動畫的持續時間將保持一致在速度較慢的設備。這些基於時間序列，也可以讓您單獨選擇和調整幀速率為每一個序列，而不是動畫的速度鎖定在應用程序的全球幀速率。
There may be more than one instance of each sprite on the stage at the same time, playing at different locations and with different durations. A sprite animation behaves like any other Corona display object -- it may be added to a group or transformed, or even used as a Box2D physics object.
可能有多個實例的每個精靈在舞台上在同一時間，打在不同地點和不同時間。一個 Sprite動畫Corona行為像任何其他顯示對象- 這可能是添加到組或轉換，或甚至作為 Box2D的物理對象。
The JungleScene sample project demonstrates using two different sprite sheets (both with uniformly-sized frames), to create animations running at different frame rates. To see an example of sprite sheet source images, view the files “greenman.png” and “runningcat.png” in that project folder.
該 JungleScene示例項目演示如何使用兩種不同的精靈片（包括均勻大小的幀），以創建動畫運行在不同的幀速率。要查看示例精靈表源圖像，查看文件“greenman.png“和”runningcat.png“在該項目文件夾。
The HorseAnimation sample project demonstrates how to use create a sprite sheet from a Lua data descriptor file and source image whose frames are non-uniformly sized and positioned in the sheet.
該 HorseAnimation示例項目演示如何使用創建一個精靈從一個 Lua表數據描述符和源文件的幀圖像非均勻大小調整和定位工作表中。
Limitations限制
If you attempt to use a sprite sheet whose width or height exceeds your device's maximum texture size, no image will be displayed.
如果您嘗試使用一個精靈表的寬度或高度超過您設備的最大紋理尺寸，無圖像將顯示。
To check the maximum texture size, use system.getinfo("maxTextureSize").
要檢查最大紋理大小，使用system.getinfo（“maxTextureSize“）。
Summary綜述
For each animation sequence, the developer specifies the following things:
對於每個動畫序列，開發商指定了以下幾點：
*Source image (the sprite sheet)
*One of the following:
*The height and width of each frame within the sprite sheet (for sprite sheets with uniformly sized frames)
*A Lua data descriptor file that describes the size, position, and other attributes of each frame (for sprite sheets with non-uniformly sized frames). Typically this would be generated by a sprite sheet packing utility.
*Location of sprite frames -- these may not be contiguous!
When drawing an instance of the sprite animation, the developer specifies:
*源圖像（精靈表）
*下列其中一項：
*高度和寬度在每幀精靈表（精靈片大小均勻的幀）
*一個 Lua數據描述符文件，它描述的大小，位置和其他屬性每幀（片精靈與非均勻大小的幀）。通常這會產生一個精靈表包裝工具。
*位置精靈框架- 這可能不是連續的！
當畫一個實例的Sprite動畫，發展商指定：
*Destination in the scene
*Optional transforms such as rotate/scale
*Length of animation (time-based)
*Looping behavior
*目的地在現場
*可選的變換，如旋轉/縮放
*長度的動畫（基於時間）
*循環行為
Sprite API精靈的API
This line makes the sprite features available under the “sprite” namespace:
這條線使精靈可用功能下的“精靈“命名空間：
require "sprite"
sprite.newSpriteSheet
sprite.newSpriteSheetFromData
These functions create new sprite sheets.
這些函數創建新的Sprite表。
The following code creates a new sprite sheet from image containing uniformly-sized frames, but does not add anything to the display list.
下面的代碼創建一個新的Sprite表從圖像含有均勻大小的框架，但是不添加任何東西到顯示列表中。
spriteSheet = sprite.newSpriteSheet("image.png", frameWidth, frameHeight)
In this case, the number of frames in the sprite sheet is assumed to be floor(imageWidth/frameWidth) * floor(imageHeight/frameHeight). They are indexed in row major order:
在這種情況下，幀數在精靈表被認為是地板（imageWidth/ frameWidth）*地板（imageHeight/ frameHeight）。他們主要是索引的行順序：
1 2 3
4 5 6
7 8 9
spriteSheet = sprite.newSpriteSheetFromData( "image.png", spriteData )
This second form takes as its second parameter a table that describes the frame sizes and positions in the source sprite sheet image.
這第二種形式作為其第二個參數表，說明該幀的大小和位置在源精靈張圖像。
The code below is an example of a sprite sheet descriptor file named test.lua. It defines a single function named getSpriteSheetData() that returns a Lua table whose elements describe the size, position, and other properties of each frame in the sprite sheet.
下面的代碼是一個例子，一個精靈表描述符文件名為 test.lua。它定義了一個函數名為 getSpriteSheetData（）返回一個 Lua表，其內容描述的大小，位置及其他性質的每一幀中的精靈表。
-- test.lua module (...) function getSpriteSheetData() local sheet = { frames = { { name = "01.png", spriteColorRect = { x = 38, y = 38, width = 50, height = 50 }, textureRect = { x = 2, y = 70, width = 50, height = 50 }, spriteSourceSize = { width = 128, height = 128 }, spriteTrimmed = true, textureRotated = false }, { name = "02.png", spriteColorRect = { x = 38, y = 36, width = 50, height = 52 }, textureRect = { x = 2, y = 242, width = 50, height = 52 }, spriteSourceSize = { width = 128, height = 128 }, spriteTrimmed = true, textureRotated = false }, } } return sheet end
And the following code creates a new sprite sheet object from the source image file ("test.png") and the data file ("test.lua") shown above.
和下面的代碼創建了一個新的Sprite表對象從源圖像文件（“test.png“）和數據文件（“test.lua“）所示。
local sprite = require("sprite")
-- In this case, test.lua is exported from Zwoptex 在這種情況下，test.lua是出口的Zwoptex
local test = require("test.lua")
-- Method defined by test.lua that returns table data defining the sprites
--方法定義 test.lua返回表中的數據定義精靈
local spriteData = test.getSpriteSheetData()
-- Load the sprite sheet in test.png using the sprite definitions from spriteData
-- 載入 test.png 到精靈片內 使用精靈定義從 spriteData
local spriteSheet = sprite.newSpriteSheetFromData( "test.png", spriteData )
In either case, creating a new sprite sheet object does not actually result in anything being added to the display list. To do that you need to create a sprite (and optionally sprite sets) from your sprite sheet object. These concepts are explained further below.
在這兩種情況下，創建一個新的Sprite表對象實際上並沒有導致任何被添加到顯示列表中。要做到這一點，你需要創建一個精靈（和可選精靈套），從你的精靈表對象。這些概念在後面進一步解釋。
Tip: You can combine sprite sheet loading into one line of code:
提示：您可以將精靈表加載到一行代碼：<兩行變一行>
local spriteSheet = sprite.newSpriteSheetFromData( "test.png", test.getSpriteSheetData() )
spriteSet = sprite.newSpriteSet(spriteSheet, startFrame, frameCount)
Creates a new sprite set from a sprite sheet. Since a single sprite sheet may contain images from unrelated game characters, a “sprite set” defines the collection of frames that belong to the same game character, which may then be subdivided into different animation sequences for playback. For example, a fighting game character would probably have different animation sequences for punching and for kicking, but these would be defined within the same sprite set.
創建一個新的Sprite設置從一個精靈表。由於單個 Sprite表可能包含不相關的遊戲人物形象，一個“精靈設定“定義的集合框架屬於同一遊戲角色，然後可再細分為不同的動畫序列的播放。例如，一個戰鬥遊戲角色將可能有不同的動畫序列，衝和腳踢，但這些會被定義在同一個精靈集。
startFrame is the index number of the first frame of the sprite, using the index defined in newSpriteSheet() above, and frameCount is the total number of frames in the set.
startFrame是指數的第一幀的精靈，使用索引定義在 newSpriteSheet（）上面，並 frameCount是總幀數的設置。
A sprite set is a Lua table containing keys to one or more animation sequences for a given character. Each sprite set is created with an initial sequence named "default", containing all frames in the set, so you can either use this default sequence immediately or define further animation sequences within the set.
一個精靈集是一個 Lua表包含一個或多個鍵動畫序列某一特定字符。每個精靈集創建一個初始的序列命名為“默認“，包含集合中的所有幀，所以你可以使用這個默認順序立即或進一步界定在規定的動畫序列。
sprite.add( spriteSet, "startFlying", startFrame, frameCount, time, [loopCount])
Adds a sequence named "startFlying" to the sprite set with the specified frames. The sequence has frameCount frames, and will play for time milliseconds. You can control the frame rate of each sequence individually by altering this time parameter.
添加一個序列命名為“startFlying“的精靈設置指定的幀。該序列已frameCount框架，並將拖延時間以毫秒為單位。您可以控制每個序列幀速率分別通過改變這個時間參數。
The optional parameter loopParam controls the looping behavior:
可選參數 loopParam控制循環的行為：
A value of 1 or greater sets the number of times the animation sequence will loop. When done it will stop on the last frame of the sequence.
A loopParam of 0 (which is the default) means that the sequence will loop indefinitely.
A loopParam of -1 means that the sequence will "bounce" back and forth exactly once (1, 2, 3, 2, 1).
Finally, a loopParam of -2 means that the sequence will bounce back and forth forever. In our 3-frame example, this would play in the following order: 1, 2, 3, 2, 1, 2, 3, 2, 1 (...) and so on.
一個值為 1或更大的設置次數將循環的動畫序列。完成後，將停止在最後一幀序列。
一個loopParam 0 的（這是默認）意味著將無限循環的順序。
一個loopParam-1意味著序列將“反彈”來回一次（1,2,3,2,1）。
最後,一個loopParam -2意味著序列將永遠來回反彈。在我們的3架例如，這將發揮以下順序：1，2，3，2，1，2，3，2，1(...)等。
spriteSheet:dispose()
Disposes of a sprite sheet and releases its texture memory. It also calls removeSelf() on all sprite instances using the sheet, removing them from the stage. All sprites, sequences, and sets that belong to the removed sprite sheet are no longer valid after calling this method, and will be garbage collected when they are no longer referenced by your application's Lua code.
處置一個精靈表並釋放它的紋理內存。它還呼籲 removeSelf（）對所有精靈情況下使用表，從舞台上刪除它們。所有的精靈，序列，並設置屬於被刪除的精靈表不再有效調用此方法後，會被垃圾收集時，他們不再被引用的應用程序的Lua代碼。
local sprite = require("sprite")
local spriteSheet = sprite.newSpriteSheet("test.png")
-- Later dispose of the sprite sheet and all of its associated sprites, sequences and sets.
spriteSheet:dispose()
si = sprite.newSprite( spriteSet )
Create a new instance of a sprite. A sprite is a DisplayObject. Sprites play one animation sequence at a time.
創建一個新的實例的一個精靈。一個精靈是一個 DisplayObject。精靈播放一動畫序列一次。
si:prepare([sequence])
Stops any currently playing animation sequence, optionally sets the new current sequence, and also moves to the first frame of that sequence. This also resets the loop counter, if any. However, this does not start playing the current sequence.
停止任何正在播放的動畫序列，可以選擇設置新的當前序列，並移動到第一幀的序列。這也將重置循環計數器,如果有的話。但是，這並不開始播放當前序列。
si:play()
Play animation sequence, starting at the current frame. Does not reset looping.
播放動畫序列，開始在當前幀。不重置循環。
si:pause()
Stop animation, but the frame remains on the last displayed frame. Playback can resume later with play().
停止動畫，但框架仍保留在最後顯示的畫面。回放可以稍後繼續與play（）。
si:addEventListener("sprite", listener)
Notify listener when the spriteInstance animation has an event.
通知偵聽器，當 spriteInstance動畫有一個事件。
The event, passed to the listener, has the following fields:
本次活動，傳遞給聽眾，有以下字段：
event.sprite The sprite that fired the event; its current properties may also be accessed via the event: e.g., event.sprite.sequence.
event.sprite 精靈的觸發事件，其目前的屬性還可以通過訪問活動：例如，event.sprite.sequence。
event.phase
The phase is one of:
該階段是一個：
"end" - the sprite stops playing 精靈停止播放
"loop" - the sprite loops (from last to first, or reverses direction) 精靈循環（從後到前,或反轉方向）
"next" - the sprite's next frame is played 精靈的下一幀播放
Also see "Custom Events" in the Corona API Reference. 另請參閱“自定義事件“，在Corona API參考。
Sprite properties 精靈屬性
animating = true/false. read only. 只讀。
currentFrame = frame # of animation. read/write. 讀 / 寫
sequence = name of currently playing sequence 正在播放的順序名稱
留言列表
