animation

content/animation defines pplaf.animation - Animation framework.
Examples: assets/animations/

Overview

pewpew has basic features, that allow you to create 30/60fps animations. PPLAF automates this process and adds a lot of flexible features.

Animation type

To define PPLAF animation, first we have to create file that returns table with animation's type. Some things are optional. If they won't be presented, they will be automatically set to certain values that shouldn't affect your animation if everything else is correct. Basic PPLAF animation looks like:

local frame_amount = 90
return {
  template = 0,
  frames_per_tick = 2,
  frame_offset = 0,
  variation_amount = 10,
  frame_amount = frame_amount,
  path = '/dynamic/pplaf/assets/meshes/flamethrower.lua',
  actions = {
    {'wait', frame_amount},
  },
}

• template - index, which defines how animation is stored and will be processed.
• frames_per_tick - if 1, every tick, mesh A is applied to entity, 30fps animation. If 2, every tick, meshes A and A + 1 are applied to entity, 60fps animation.
• frame_offset - additional offset, which allows you to store additional frames after ones, used in animation. If isn't presented, it is automatically set to 0.
• variation_amount - amount of variations, animation has. If not presented, it is automatically set to 1.
• frame_amount - amount of frames one animation's variation has.
• path - path to file, containing animation or folder, containing animation files, named from 1.lua to N.lua.
• actions - table, containing actions, tables with parameters, that tell PPLAF, how it should animate entity in that moment.

The best practice would be defining animation type, loading it and requiring it by mesh/animation/animation generator. This way you can change parameters once and they will be changed both in animation settings and in mesh itself.
More information about how animation framework requires you to store meshes is available at Storing Frames.

Animation

We defined animation type and created entity, containing corresponding animation. Let's see, what stored in this animation:

• type - table, containing animation type.
• frame - current frame. Frame is incremented depending on frames_per_tick and frame_offset.
• action - index of current action.
• action_param - table, containing copy of current action from animation.type.actions. Parameters in this table will be changed over time, they're used to process action.
• variation_index - index of variation[0; N - 1], that will be used by this animation. It is set to 0, but you can also call entity:set_animation_variation(index) to change this value and corresponding offset.
• variation_offset - automatically calculated, depending on variation_index and frame_amount. It is used to calculate current frame.

Template

animation.templates contains templates, which define how animation is stored and will be processed:

• sf = 0 - animation is stored in single file, A variations are stored in this file, every variation contains B frames.
• mf_variation = 1 - animation is stored in multiple files, every file represents 1 variation of animation and contains B frames.
• mf_frame = 2 - animation is stored in multiple files, every file represents 1 frame of animation and contains A variations.
• mf_variated_frame = 3 - animation is stored in multiple files, every file represents 1 variation of 1 frame.

Storing Frames

PPLAF animations require you to store frames in certain way. Templates can change these requirements, but overall idea is same. You store B frames for single variation. These frames are divided by ticks, so there are C frames per tick. In C frames first or first 2 frames(depending on frames_per_tick value) are used by animation framework to animate entity. Next frames aren't used, but can be allocated for manual use by changing value of frame_offset. The most common use for this additional frame is damaged variation of entity mesh. Same can be achieved by modifying color of the mesh, if it's simple enough or by creating another mesh, containing only frames with damaged entity. So, you have plenty options. So, C = frames_per_tick + frame_offset and you alternate C frames for every tick.

Actions

PPLAF animations require you to determine, how entity will be animated. Actions system allows you to create order of animations, loops, etc. Action is filled like:

{'wait', 10}
{100, 10}

First parameter is action type or corresponding index. Names are automatically replaced with corresponding indexes when animation is loaded. Next parameters are defined by action type itself. Action types are stored in animation.actions:

• wait - {100, N} - mesh isn't set, waiting for N ticks; frames aren't incremented; after N frames go to next action
• wait_and_increment - {101, N} - mesh isn't set, waiting for N ticks; frames are incremented; after N frames go to next action
• wait_and_decrement - {102, N} - mesh isn't set, waiting for N ticks; frames are decremented; after N frames go to next action
• animate - {200, A} - mesh is set to current frame while frame is in less than A; frames are incremented; after frame is equal to A go to next action
• animate_back - {201, A} - mesh is set to current frame while frame is in more than A; frames are decremented; after frame is equal to A go to next action
• loop - {300, A, B} - mesh is set to current frame, after frame is equal to B, frame is set to A; frames are incremented
• loopW - {301, A, B, Q} - mesh is set to current frame, after frame is equal to B, frame is set to A; frames are incremented; after Q loops go to next action(last frame is kept instead of being reset to A)
• loop_back - {302, A, B} - mesh is set to current frame, after frame is equal to A, frame is set to B; frames are decremented
• loop_backW - {303, A, B, Q} - mesh is set to current frame, after frame is equal to A, frame is set to B; frames are decremented; after Q loops go to next action(last frame is kept instead of being reset to B)
• loop_back_forth - {304, A, B} - mesh is set to current frame; mesh is incremented/decremented after reaching corresponding frame
• loop_back_forthW - {305, A, B, Q} - mesh is set to current frame; mesh is incremented/decremented after reaching corresponding frame; after Q loops(forth-back loops, double for full loops) go to next action(last frame is kept instead of being reset to A/B)
• set_frame - {400, N} - frame is set to N; go to next action

pplaf.animation

• load_by_typed_dir(str path, ...)
• load_by_typed_files(str path, ...)
• preload_all()

Variables

types - table, containing loaded types with type names as their keys.
template - table, containing indexes, which determine how animation is stored and will be processed.
actions - table, containing indexes, which determine how animation will be processed while certain action is active.

Functions

nil load_by_typed_dir(str path, ...)

Loads animations from folder. Folder must contain folders, named by names, presented in ..., and those must contain file with animation type, named as animation.lua.

pplaf.animation.load_by_typed_dir('/dynamic/assets/entities/',
  'rotating_triangle',
  'strange_triangle'
)

nil load_by_typed_files(str path, ...)

Loads animations from folder. Folder must contain files, named as presented in ....

pplaf.animation.load_by_typed_files('/dynamic/assets/animations/',
  'rotating_triangle',
  'strange_triangle'
)

nil preload_all()

Loads all animations to avoid lag and/or delay while accessing mesh for the first time.

pplaf.animation.preload_all()