TrainAnimationRecorder API

This page covers the API for the TrainAnimationRecorder module.

Whereas the Compiler API is like a state machine, this is more functional and modular with it split into many classes. Each state is in it's own class. The two most important classes are the KeyframeRecorder and PhysicsState.

• KEYFRAME_TRANSITION_TYPE
• KeyframeData
• KeyframeDataBuilder
• PhysicsState
• KeyframeRecorder
• TriggerRecorder
• GetPassedTriggers
• GetPassedTriggersBuilder
• PhysicsSimulator
  • Simulate
  • SimulationState
  • SimulationStateBuilder
• EasingSimulator
  • EASINGS
  • Simulate
  • SimulationState
  • SimulationStateBuilder
• Exporter
  • Exporter
  • ExporterBuilder

KEYFRAME_TRANSITION_TYPE

TrainAnimationRecorder.KEYFRAME_TRANSITION_TYPE {
    NONE: 0,
    LINEAR: 1,
}

When tweening between two Keyframes, the first keyframe's transition type is used.

NONE: No tweening is used.

LINEAR: Tweens linearly.

KeyframeData

TrainAnimationRecorder.KeyframeData {
    Position: number,
    TrackSpeed: number,
    Track: string,

    IsTrainBackwards: boolean,
    HasPassedTrackEnd: boolean,
    HasPassedTrackEndDirection: boolean,

    TransitionType: KEYFRAME_TRANSITION_TYPE,

    Length: number,
}

KeyframeData contains all the uncompressed data for one keyframe in an animation.

Properties

Position: The position of the train on the track

TrackSpeed: The speed of the train at this keyframe

Track: The name of the track

IsTrainBackwards: If true, makes the train model appear to move backwards along the track. Useful for doing so without changing the direction of the track points.

HasPassedTrackEnd: If true, the train has passed the end of the track (the track length) between the last keyframe.

HasPassedTrackEndDirection: The direction the train has passed the track end.

TransitionType: The type of transition used to lerp Position and TrackSpeed values between two keyframes. When tweening between two Keyframes, the first keyframe's transition type is used.

Length: The length in seconds of this keyframe.

Constructors/Deconstructors

new

KeyframeData.new() -> KeyframeData

Constructor. Creates and returns a new KeyframeData.

FromData

KeyframeData.FromData(data: table) -> KeyframeData

Constructor. Constructs a new KeyframeData from a table.

Methods

Clone

KeyframeData:Clone() -> KeyframeData

Clones the KeyframeData

KeyframeDataBuilder

TrainAnimationRecorder.KeyframeDataBuilder {
}

A Builder pattern implementation for creating a new KeyframeData.

Constructors/Deconstructors

new

KeyframeDataBuilder.new() -> KeyframeDataBuilder

Constructor. Constructs a new KeyframeDataBuilder.

Destroy

KeyframeDataBuilder:Destroy() -> nil

Destroys this object

Methods

Build

KeyframeDataBuilder:Build() -> KeyframeData

Builds a new KeyframeData from this builder. Does NOT destroy the Builder.

Finish

KeyframeDataBuilder:Finish() -> KeyframeData

Builds a new KeyframeData from this builder then destroys this object

WithPosition

KeyframeDataBuilder:WithPosition(position: number) -> self

WithTrack

KeyframeDataBuilder:WithTrack(trackName: string) -> self

WithTrackSpeed

KeyframeDataBuilder:WithTrackSpeed(trackSpeed: number) -> self

WithLength

KeyframeDataBuilder:WithLength(trackSpeed: number) -> self

WithTransitionType

KeyframeDataBuilder:WithTransitionType(keyframeTransitionType: KeyframeTransitionType) -> self

WithHasPassedTrackEnd

KeyframeDataBuilder:WithHasPassedTrackEnd(direction: boolean) -> self

WithTrainDirection

KeyframeDataBuilder:WithTrainDirection(direction: boolean) -> self

PhysicsState

TrainAnimationRecorder.PhysicsState {
    CFrameTrain: CFrameTrain,

    CurrentSpeed: number,
    IsMovingForward: boolean
}

State for the physics of a train. Used to record it's CurrentSpeed and movement direction.

• CFrameTrain provides "collision" data.
• CurrentSpeed is the current speed of the train.
• IsMovingForward can be used to determine if the train's movement direction has changed.

Constructors/Deconstructors

new

PhysicsState.new(cframeTrain: CFrameTrain) -> PhysicsState

Constructor. Creates a new PhysicsState.

Methods

Clone

PhysicsState:Clone() -> PhysicsState

Clones this PhysicsState.

ResetPhysics

PhysicsState:ResetPhysics() -> nil

Resets the physics data of this state.

• Will set CurrentSpeed back to 0

KeyframeRecorder

TrainAnimationRecorder.KeyframeRecorder {
    KeyframeData: KeyframeData[],

    Length: number,
    OnKeyframeAdded: Signal,
}

Holds all the keyframes for an animation.

Signals

OnKeyframeAdded

TrainAnimationRecorder.OnKeyframeAdded(keyframe: KeyframeData)

Fired when a new keyframe is added to the recorder.

Constructors/Deconstructors

new

KeyframeRecorder.new() -> KeyframeRecorder

Constructor.

Destroy

KeyframeRecorder:Destroy() -> nil

Deconstructor.

Methods

Clone

KeyframeRecorder:Clone() -> KeyframeRecorder

Clones this KeyframeRecorder.

CloneFrom

KeyframeRecorder:CloneFrom(startIndex: uint, endIndex: uint) -> KeyframeRecorder

Clones this KeyframeRecorder between the range given.

Reverse

KeyframeRecorder:Reverse() -> self

Reverses the order of all the Keyframes in this recorder.

Append

KeyframeRecorder:Append(otherKeyframeRecorder: KeyframeRecorder) -> KeyframeRecorder

Adds the keyframes from the given KeyframeRecorder to the end of it's own list.

AppendToBeginning

KeyframeRecorder:AppendToBeginning(otherKeyframeRecorder: KeyframeRecorder) -> KeyframeRecorder

Adds the keyframes from the given KeyframeRecorder to the start of it's own list.

AddKeyframe

KeyframeRecorder:AddKeyframe(keyframeData: KeyframeData) -> nil

Adds the keyframe to the end of it's own list.

AddKeyframeToBeginning

KeyframeRecorder:AddKeyframeToBeginning(keyframeData: KeyframeData) -> nil

Adds the keyframe to the start of it's own list.

AddTimeAmountOfKeyframe

KeyframeRecorder:AddTimeAmountOfKeyframe(keyframeData: KeyframeData, timeAmount: number, ?timeInterval: number) -> nil

Clones and adds the given KeyframeData to itself such that the total length or timeInterval of the keyframes adds to the timeAmount.

If timeInterval is not given, it uses the Length attribute of the given KeyframeData

GetKeyframes

KeyframeRecorder:GetKeyframes(rangeStart: number, rangeEnd: number) -> KeyframeData[]

Returns an array of KeyframeData from this recorder in the given range. Range defaults to 1 and #self.KeyframeData.

GetFirstKeyframe

KeyframeRecorder:GetFirstKeyframe() -> KeyframeData

Returns the first keyframe of this recorder.

GetLastKeyframe

KeyframeRecorder:GetLastKeyframe() -> KeyframeData

Returns the last keyframe of this recorder.

GetLastTrackPosition

KeyframeRecorder:GetLastTrackPosition() -> number

Returns the TrackPosition value of the last KeyframeData

GetLength

KeyframeRecorder:GetLength() -> number

Returns the total length of all the keyframes in this recorder

CalculateLength

KeyframeRecorder:CalculateLength() -> number

Calculates and returns the length of all the keyframes in this recorder

BuildKeyframe

KeyframeRecorder:BuildKeyframe() -> KeyframeDataBuilder

Returns a KeyframeDataBuilder that automatically adds it's KeyframeData to the recorder on build.

---

TriggerRecorder

TrainAnimationRecorder.TriggerRecorder {
    TriggerData: TriggerData[]
}

Holds triggers and their time positions for an animation.

TriggerData

TriggerData {
    Name: string,
    Position: number
}

Constructors/Deconstructors

Struct used when adding triggers to a TriggerRecorder

new

TriggerRecorder.new() -> TriggerRecorder

Constructor

Destroy

TriggerRecorder:Destroy() -> nil

Deconstructor

Methods

Clone

TriggerRecorder:Clone() -> TriggerRecorder

Clones this.

Combine

TriggerRecorder:Combine(otherTriggerRecorder: TriggerRecorder) -> nil

Combines the TriggerData in the given TriggerRecorder to this recorder.

Shift

TriggerRecorder:Shift(interval: number) -> nil

Shifts the position of all the TriggerData in this Recorder by the given interval.

Add

TriggerRecorder:Add(triggerID: string, position: number) -> nil

Adds a new trigger data to this recorder that can be called in your animation.

• triggerID is the name of the trigger.
• position is the time position in the animation.

GetPassedTriggers

TrainAnimationRecorder.GetPassedTriggers(keyframeRecorder: KeyframeRecorder, triggerList: TriggerData, cframeTrack: CFrameTrack, ?trackName: string, ?rangeStart: number, ?rangeEnd: number) -> TriggerRecorder

Passes through all the Keyframes in the given KeyframeRecorder checking if it passed any of the positions in the triggerList on the given track. Returns a TriggerRecorder containing all the passed triggers.

GetPassedTriggersBuilder

A Builder pattern implementation for GetPassedTriggers. Useful for adding new TriggerData.

Constructors/Deconstructors

new

GetPassedTriggersBuilder.new() -> GetPassedTriggersBuilder

Constructor

Destroy

GetPassedTriggersBuilder:Destroy() -> nil

Deconstructor

Methods

Build

GetPassedTriggersBuilder:Build() -> TriggerRecorder

Finish

GetPassedTriggersBuilder:Finish() -> TriggerRecorder

WithKeyframeRecorder

GetPassedTriggersBuilder:WithKeyframeRecorder(keyframeRecorder: KeyframeRecorder) -> self

Required!

The KeyframeRecorder that GetPassedTriggers will look through.

WithTrigger

GetPassedTriggersBuilder:WithKeyframeRecorder(name: string, position: number) -> self

Adds a trigger to look for.

WithTriggers

GetPassedTriggersBuilder:WithKeyframeRecorder(triggerList: TriggerData[]) -> self

Adds triggers to look for from a list.

WithCFrameTrack

GetPassedTriggersBuilder:WithKeyframeRecorder(cframeTrack: CFrameTrack) -> self

Required!

The track whose length is used with the HasPassedTrackEnd flag.

WithTrackName

GetPassedTriggersBuilder:WithKeyframeRecorder(trackName: string) -> self

The track name used to look for the trigger data. If no name given, the CFrameTrack's name is used.

WithRangeStart

GetPassedTriggersBuilder:WithKeyframeRecorder(rangeStart: number) -> self

The start range. Default is 1

WithRangeEnd

GetPassedTriggersBuilder:WithKeyframeRecorder(rangeEnd: number) -> self

The end range. Default is #KeyframeRecorder.KeyframeData

---

PhysicsSimulator (Module)

TrainAnimationRecorder.PhysicsSimulator {
    Simulate: function,
    SimulationState: SimulationState,
    SimulationStateBuilder: SimulationStateBuilder
}

Used to simulate coaster and track physics. Uses TrackSectionsData, which defines the type sections for the given track. Also utilizes the GetAngle method of CFrameTrack.

Simulate

PhysicsSimulator.Simulate(simulationState: PhysicsSimulationState, physicsState: PhysicsState) -> KeyframeRecorder, PhysicsSimulationStopReason

Simulates track/coaster physics until the stop types defined in the simulationState. physicsState will be changed as goes through it's loop.

SimulationStopReason

SimulationStopReason {
    Type: string
}

-- the names of these are SimulationStopReason's Type value
PassedStopPosition {
    Name: string,
    Position: number,
    TimeDifference: number,
}

DirectionChanged {
    Direction: boolean
}

StoppedByTrackType {

}

HasValleyed {

}

ReachedMaxCompileTime {

}

StopPositionData

StopPositionData {
    Position: number,
    Name: string,
    StopExactly: boolean
}

Defines a stop position for stopping the simulation.

SimulationState

PhysicsSimuator.SimulationState {
    CFrameTrack: CFrameTrack,
    TrackSectionsData: TrackSectionsData,

    StopPositions: StopPositionData[],
    StopWhenDirectionChanges: boolean,

    IsValleying: boolean,
    IsValleyingRange: number,
    MaxValleyTime: number,
    TimeValleying: number,

    ClampPositionToTrackLength: boolean,
    IsTrainBackwards: boolean,
    TimeInterval: number,
    RecordInterval: number,
    MaxSimulationTime: number,

    CurrentPosition: number,

    HasPassedTrackEnd: boolean,

    Gravity: number,
    Friction: number,
}

The state for the PhysicsSimulator.

Properties

CFrameTrack: Track used for this simulator.

TrackSectionsData: Track Sections used for this simulator.

StopPositions: List of stop positions. If the simulator passes any of the positions in this list, it will stop the simulation.

StopWhenDirectionChanges: If the direction changes (due to a rollback or etc.), it will stop the simulation.

IsValleying: If true, then the train's speed is under a threshold that determines if it is valleying. This value is given by IsValleyingRange.

IsValleyingRange: Speed threshold to determine if a train is stuck.

MaxValleyTime: If the train valleys for above this time, it will stop the simulation.

TimeValleying: Time spent valleying

ClampPositionToTrackLength: If true, whenever the train exceeds the track length or goes under 0, it will clamp it between. Will also flag HasPassedTrackLength in the Keyframe.

IsTrainBackwards: Marks train model as backwards

TimeInterval: Length simulated (Not used)

RecordInterval: Length recorded interval.

MaxSimulationTime: Max time. Prevents infinite loops.

CurrentPosition: Current position on the track.

HasPassedTrackEnd: Flags passed track end.

Gravity: Gravity

Friction: Friction

SimulationStateBuilder

PhysicsSimulator.SimulationStateBuilder {

}

Constructors/Deconstructors

new

SimulationStateBuilder.new() -> SimulationStateBuilder

Destroy

SimulationStateBuilder:Destroy() -> nil

Methods

Build

SimulationStateBuilder:Build() -> PhysicsSimulationState

Finish

SimulationStateBuilder:Finish() -> PhysicsSimulationState

WithGravity

SimulationStateBuilder:WithGravity(gravity: number) -> self

WithFriction

SimulationStateBuilder:WithFriction(friction: number) -> self

WithCFrameTrack

SimulationStateBuilder:WithCFrameTrack(cframeTrack: CFrameTrack) -> self

WithTrackSectionsData

SimulationStateBuilder:WithTrackSectionsData(trackSectionsData: TrackSectionsData) -> self

WithStartPosition

SimulationStateBuilder:WithStartPosition(position: number) -> self

WithPositionClampedToTrackLength

SimulationStateBuilder:WithPositionClampedToTrackLength(value: boolean) -> self

WithTrainDirection

SimulationStateBuilder:WithTrainDirection(direction: boolean) -> self

WithTimeInterval

SimulationStateBuilder:WithTimeInterval(interval: number) -> self

WithRecordInterval

SimulationStateBuilder:WithRecordInterval(interval: number) -> self

WithMaxTime

SimulationStateBuilder:WithMaxTime(maxTime: number) -> self

UntilStopPosition

SimulationStateBuilder:UntilStopPosition(stopPosition: number, name: string, ?stopExactly: boolean = false) -> self

UntilStopPositions

SimulationStateBuilder:UntilStopPositions(stopPositionsData: StopPositionData[]) -> self

UntilDirectionChanges

SimulationStateBuilder:UntilDirectionChanges(value: boolean) -> self

---

EasingSimulator (Module)

TrainAnimationRecorder.EasingSimulator {
    EASING: EASING,

    Simulate: function(),
    SimulationState: SimulationState,
    SimulationStateBuilder: SimulationStateBuilder
}

Records keyframes using an Easing/Tween.

EASING

Enum

https://easings.net/

Linear
InQuad
OutQuad
InOutQuad
OutInQuad
InCubic
OutCubic
InOutCubic
OutInCubic
InQuart
OutQuart
InOutQuart
OutInQuart
InQuint
OutQuint
InOutQuint
OutInQuint
InSine
OutSine
InOutSine
OutInSine
InExpo
OutExpo
InOutExpo
OutInExpo
InCirc
OutCirc
InOutCirc
OutInCirc
InElastic
OutElastic
InOutElastic
OutInElastic
InBack
OutBack
InOutBack
OutInBack
InBounce
OutBounce
InOutBounce
OutInBounce

Simulate

EasingSimulator.Simulate(simulationState: SimulationState, physicsState: PhysicsState) -> KeyframeRecorder

Records keyframes using an Easing/Tween and returns a new KeyframeRecorder containing them.

SimulationState

EasingSimulator.SimulationState {
    CFrameTrack: CFrameTrack,

    CurrentPosition: number,
    IsTrainBackwards: boolean,

    TweenType: EasingSimulator.EASING,
    PositionChange: number,
    ClampPositionToTrackLength: boolean,

    Duration: number,
    StartTime: number,
    EndTime: number,
}

SimulationStateBuilder

EasingSimulator.SimulationStateBuilder {

}

Builder pattern implementation for EasingSimulationState.

Constructors/Deconstructors

new

SimulationStateBuilder.new() -> SimulationStateBuilder

Methods

WithCFrameTrack

SimulationStateBuilder:WithCFrameTrack(cframeTrack: CFrameTrack) -> self

Required

WithTweenType

SimulationStateBuilder:WithTweenType(tweenType: EASINGS) -> self

Required

WithDuration

SimulationStateBuilder:WithDuration(duration: number) -> self

Required

Duration must be a number greater than 0.

WithStartPosition

SimulationStateBuilder:WithStartPosition(position: number) -> self

WithTrainDirection

SimulationStateBuilder:WithTrainDirection(direction: boolean) -> self

WithPositionChange

SimulationStateBuilder:WithPositionChange(change: number) -> self

WithTimeInterval

SimulationStateBuilder:WithTimeInterval(timeInterval: number) -> self

WithStart

SimulationStateBuilder:WithStart(rangeStart: number) -> self

WithEnd

SimulationStateBuilder:WithEnd(rangeEnd: number) -> self

WithRange

SimulationStateBuilder:WithRange(?rangeStart: number = 0, ?rangeEnd: number = self.Duration) -> self

WithPositionClampedToTrackLength

SimulationStateBuilder:WithPositionClampedToTrackLength(?value: boolean = true) -> self

---

Exporter (Module)

TrainAnimationRecorder.Exporter {
    Exporter: Exporter,
    ExporterBuilder: ExporterBuilder
}

Used to export KeyframeData to Animations for the Framework

Exporter

Exporter.Exporter {
    TimeInterval: number,
    Length: number,
    NumberOfKeyframes: number,
    TracksData: TrackData[],
    TrackUIDKeyframes: TrackUIDKeyframes[],
    PassedTrackEndKeyframes: HashMap<uint, boolean>,
    TrainDirectionKeyframes: TrainDirectionKeyframe[],
    Triggers: TriggerInfo[],
    Keyframes: KeyframeData[],
}

A class that provides methods to export KeyframeData as an animation for use with the Framework

Constructors/Deconstructors

new

Exporter.new() -> Exporter

create

Exporter.create(keyframeRecorder: KeyframeRecorder, triggerRecorder: TriggerRecorder, registeredCFrameTracks: Dictionary<CFrameTrack>, rangeStart: number, rangeEnd: number) -> Exporter

Methods

AsModuleScript

Exporter:AsModuleScript() -> ModuleScript

Exports as a module script with (mostly) human readable lua.

AsBitBufferString

Exporter:AsBitBufferString() -> string

Exports as a BitBuffered string. You can use this string however you like.

AsBitBufferModule

Exporter:AsBitBufferModule() -> ModuleScript

Exports as a ModuleScript which returns a BitBuffer string.

ExporterBuilder

Exporter.ExporterBuilder

Builder pattern implementation for Exporter

Constructors/Deconstructors

Methods

WithKeyframeRecorder

ExporterBuilder:WithKeyframeRecorder(keyframeRecorder: KeyframeRecorder) -> self

Required

WithCFrameTrack

ExporterBuilder:WithCFrameTrack(cframeTrack: CFrameTrack, ?name: string) -> self

WithCFrameTracks

ExporterBuilder:WithCFrameTracks() -> self

WithTriggerRecorder

ExporterBuilder:WithTriggerRecorder(triggerRecorder: TriggerRecorder) -> self

Required

WithRangeStart

ExporterBuilder:WithRangeStart(rangeStart: number) -> self

WithRangeEnd

ExporterBuilder:WithRangeEnd(rangeEnd: number) -> self