| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| en:orx:config:settings_structure:orxanim [2009/12/22 19:05 (16 years ago)] – Added custom events iarwain | en:orx:config:settings_structure:orxanim [2023/09/19 23:35 (19 months ago)] (current) – sausage |
|---|
| === Animation Set === | === Animation Set === |
| |
| <code ini>[AnimationSetTemplate] | <code ini> |
| AnimationList = AnimationTemplate1#AnimationTemplate2#... | [AnimationSetTemplate] |
| LinkList = LinkTemplate1#LinkTemplate2#... | Frequency = <float> |
| Frequency = <float></code> | KeepInCache = <bool> |
| | StartAnim = Animation |
| | StartAnimList = Animation1 # ... # AnimationN |
| | Prefix = <string> |
| | Digits = <int> |
| | Animation = <string> |
| | Animation = <string> |
| | Animation = empty |
| | Animation-> = {.!+-}Animation1 # ... # {.!+-}AnimationN |
| |
| === Animation === | </code> |
| |
| <code ini>[AnimationTemplate] | === Animation and Animation<N> === |
| DefaultKeyDuration = <float> | |
| KeyData<N> = GraphicTemplate | |
| KeyDuration<N> = <float> | |
| EventName<N> = <string> | |
| EventTime<N> = <float> | |
| EventValue<N> = <float></code> | |
| |
| === Animation link === | <code ini> |
| | [AnimationTemplate] |
| | Texture = path/to/ImageFile.ext |
| | TextureOrigin = <vector> |
| | TextureSize = <vector> |
| | Text = TextTemplate |
| | Direction = left | right | down | up # left | right | down | up |
| | FrameSize = <vector> |
| | KeyDuration = <float> |
| | |
| | [AnimationTemplate<N>] ; eg: AnimationTemplate0003 |
| | KeyEvent = <string> |
| | TextureOrigin = <vector> |
| | TextureSize = <vector> |
| | FrameIndex = <int> |
| | String = "string to display" |
| | KeyDuration = <float> |
| | |
| | </code> |
| |
| <code ini>[LinkTemplate] | |
| Source = SourceAnimationTemplate | |
| Destination = DestinationAnimationTemplate | |
| Priority = <int> | |
| Property = immediate | cleartarget</code> | |
| |
| |
| === Animation set === | === Animation set === |
| |
| Here's a list of the available properties for an animation: | <WRAP center round box 90%> |
| * ''AnimationList'': List of all the animations (config names) that are part of this set. Up to 256 animations can be defined. This property //needs// to be defined. | This ''AnimationSet'' section will become the parent of any ''Animation'' section used by it. So they will become common properties to all the animations or animation frames. Properties such as ''FrameSize'', ''Texture'', ''KeyDuration'' or ''Direction'' can be defined here. |
| * ''LinkList'': List of all links ((a link is an available transition from an animation to another one)) that are part of this set. Up to 256 links can be defined. This property //needs// to be defined. | </WRAP> |
| * ''Frequency'': Relative frequency that will be applied to all animations of this set when they're played. Its default value is 1.0, which means the animation will be played with the timing defined in the config. | |
| |
| === Animation === | |
| |
| Here's a list of the available properties for an animation set: | Here's a list of the available properties for an animation set: |
| * ''DefaultKeyDuration'': Default duration for all defined keys, in seconds. This duration can be overridden locally for any defined key. By default its value is 0.0 and needs to be defines unless every key has a local value. | * ''Frequency'': Relative frequency to which the animations will be played. Defaults to 1.0, which means the animation will be played with the timing defined in the config. |
| * ''KeyData<N>'': All the keys needs to be defined sequencially, starting with the ''KeyData1''. No gap is allowed in the numbers. For every key, the value is the [[orxGRAPHIC]] that will be rendered when the animation cursor points on this key, when played. At least one key (''KeyData1'') needs to be defined. | * ''KeepInCache'': If true, the animation set will always stay in cache, even if not currently used by any objects. Can save time but costs memory. Defaults to false. |
| * ''KeyDuration<N>'': For any key defined (with ''KeyData<N>''), a duration, in seconds, can be specified. If none is defined, the ''DefaultKeyDuration'' will be used instead. | * ''StartAnim'': Entry point of the animation graph, first animation to be played by default. If this StartAnim is defined, StartAnimList will be ignored. |
| * ''EventName<N>'': Custom events can be associated to animations. They allow to synchronize with specific part of animations. | * ''StartAnimList'': Multiple entry points for disjointed animation graphs. The first animation in the list will be played by default. Ignored if StartAnim is defined. |
| * ''EventTime<N>'': Specifies when (ie. time stamp) the corresponding event will be sent. | * ''Prefix'': Prefix that will used in front of all animation names and frames, ie: 0001. Defaults to empty string. |
| * ''EventValue<N>'': Optional value for an event. By default its value is 0.0. | * ''Digits'': How many digits will be used for the animation frame suffixes. Defaults to 0 (ie. as many digits as needed, without any prefixed 0). |
| | * ''Animation'': The first value, optional, defines a name for the animation config template to use, defaults to the key itself. The second value, optional, specifies how many frames should be created: >0 => maximum frames to be loaded, -1 => as many frames as can fit inside the whole texture, 0 => as many frames as are defined in config, defaults to -1. |
| | * ''Animation'': In this mode, separate texture files are expected for all the frames. The first value defines the animation base file name, the second one defines the file extension. |
| | * ''Animation'': In this mode, an empty animation (with no keys) will be created. |
| | * ''Animation->'': Defines all the possible transitions (ie. links) coming from Animation. The optional prefixes are properties for the link: . => immediate, ! => clear target, + => high priority, - => low priority. Defaults to looping onto itself if not defined. |
| |
| Example: | === Animation === |
| |
| <code ini>[MyAnimation] | <WRAP center round box 90%> |
| DefaultKeyDuration = 0.1 | NB: Do not use manual inheritance at the section level as it will be overridden at runtime; it's parent will then become the animation set section. |
| KeyData1 = MyGraphic1 | </WRAP> |
| KeyData2 = MyGraphic2 | |
| KeyDuration2 = 0.2; <= this key will be displayed twice the time of the other keys | |
| KeyData3 = MyGraphic1; <= Reusing the same content as for the first key | |
| ... | |
| EventName1 = SetSoundVolume | |
| EventTime1 = 0.1 | |
| EventValue1 = 1.0 | |
| EventName2 = SetSoundVolume | |
| EventTime2 = 0.5 | |
| EventValue2 = 0.0 | |
| EventName3 = Explode | |
| EventTime3 = 0.5 | |
| ... | |
| </code> | |
| |
| === Animation link === | Here's a list of the available properties for an animation: |
| | * ''Texture'': path/to/ImageFile.ext See GraphicTemplate for more details on this property. If provided, Text property will be ignored. |
| | * ''TextureOrigin'': Defines the origin of the texture from which to get the frames. Defaults to top left corner, ie. (0, 0, 0). Unused in the case of Text animation. |
| | * ''TextureSize'': Defines the size of the texture from which to get the frames. Defaults to the actual physical size of the texture. Unused in the case of Text animation. |
| | * ''Text'': Text animations are supported provided that a Text property is defined at the animation level (here) and no Texture is defined. In this case, the animation should be defined with a value of 0 in the animation set (ie. retrieve frame data from config). |
| | * ''Direction'': Defines how the frames are read inside the texture. First value defines the direction of the rows, second one the direction of the columns. Defaults to right # down (ie. western writing direction). Examples: left|right|down|up # left|right|down|up |
| | * ''FrameSize'': Default size of all the frames of this animation. Unused in the case of Text animation. If not defined in the case of a single frame animation, defaults to the same value as TextureSize. |
| | * ''KeyDuration'': Default key duration for all the frames of this animation. |
| |
| Here's a list of the available properties for an animation link: | |
| * ''Source/Destination'': Defines the source and destination animations for the link, ie. the start and end of a possible transition. These properties //need// to be defined. | |
| * ''Priority'': Defines the priority of this link, rangin from 0 (lowest) to 15 (highest). Priorities are mostly used to define default transitions when no target animation is specified for the current object. By default its value is 8 which means a medium priority. | |
| * ''Property'': Defines the property of the link, it can either be ''immediate'', ''cleartarget''. If a link is ''immediate'' it means the transition will occur immediately instead of waiting for the end of the source animation before taking place. If a link is ''cleartarget'' it means that it will reset object's current target animation when the link is used. By default none of these properties are defined, which means the transition will occur //after// the source animation has been completely played and won't reset object's current target. | |
| |
| Example: | === Animation<N> === |
| <code ini>[LinkSitAnimLoop] | |
| Source = SitAnim | |
| Destination = SitAnim | |
| Priority = 15; <= this is our transition of choice if no target anim is requested, we just cycle here for ever =) | |
| |
| [LinkSitToStandUp] | For example: Animation0004 or Animation0005 etc |
| Source = SitAnim | |
| Destination = StandUpAnim | |
| Property = immediate; <= that means we won't wait for the end of the SitAnim cycle before going to StandUpAnim | |
| |
| [LinkStandUpToRun] | <WRAP center round box 90%> |
| Source = StandUpAnim | NB: Do not use manual inheritance at the section level as it will be overridden at runtime: its parent will then become the animation section. |
| Destination = RunAnim</code> | </WRAP> |
| |
| Now in the code, if we're currently playing the ''SitAnim'' and we issue | Here's a list of the available properties for an animation frame override: |
| | * ''KeyEvent'': Optional. Defines a custom event that will be sent when this key is played. The first value is the event's name, the second one, the event's numerical value, is optional and defaults to 0.0. |
| | * ''TextureOrigin'': Optional. Overrides the computed origin of the frame. Only define it for manual override. If this is defined, FrameIndex will be ignored. |
| | * ''TextureSize'': Optional. Overrides the default size of the frame (the FrameSize attribute in the animation/Animation Set). Only define it for manual override. |
| | * ''FrameIndex'': Optional. Overrides the current frame's texture origin based on the animation's FrameSize and Direction. Only define it for manual override. Ignored if TextureOrigin is defined for this frame. |
| | * ''String'': Optional. Only used for Text animations. |
| | * ''KeyDuration'': Optional. Overrides the default key duration of the frame. |
| | * //Any other Graphic property like Pivot or Flip can be used here.// |
| |
| <code c>orxObject_SetTargetAnim(MyHero, "RunAnim");</code> | Examples: |
| |
| MyHero will first play immediately the ''StandUpAnim'' and then go to the ''RunAnim'' without you having to wait for any animation message or anything. You can listen to the ''orxEVENT_TYPE_ANIM'' events if you still want to be notified when transitions occur. | See: [[en:tutorials:animation:animation_walkthrough|Animation Walk-through]]. |
| | |
| | |
| | ===== General things to note on the Animation System ===== |
| | |
| | You can listen to the ''orxEVENT_TYPE_ANIM'' events if you still want to be notified when transitions occur. |
| |
| Between two animations, the calculated path will take the highest priority links at each step and if two links with the same priority are found, it will then take the one that leads to the shortest path (ie. the least amount of links needed to reach destination). | Between two animations, the calculated path will take the highest priority links at each step and if two links with the same priority are found, it will then take the one that leads to the shortest path (ie. the least amount of links needed to reach destination). |
| |
| **NB: If you don't feel at ease with this [[wp>Graph_(mathematics)|graph system]], you can still define all your animations separately and then do all the transitions manually every time the current animation has been completely played (listening to the ''orxANIM_EVENT_STOP'' event, for example).** | **NB: If you don't feel at ease with this [[wp>Graph_(mathematics)|graph system]], you can still define all your animations separately and then do all the transitions manually every time the current animation has been completely played (listening to the ''orxANIM_EVENT_STOP'' event, for example).** |
| | |
| | ==== Latest config settings for the Development Version ==== |
| | {{section>en:orx:config:developmentversion#&noheader&nofooter&noeditbutton}} |
| |
