From 78222b1004ac04d7049a4e6bf1421b574ac97435 Mon Sep 17 00:00:00 2001 From: Israel Uche Date: Sun, 1 Mar 2026 00:24:08 -0500 Subject: [PATCH 01/21] Added Animation, Tilemaps, and many more --- docs/source/api/animation.rst | 385 +++++++++++++++++++++++++++++ docs/source/api/entity.rst | 18 ++ docs/source/api/graphics.rst | 117 ++++++++- docs/source/api/input.rst | 128 ++++++++++ docs/source/api/math_types.rst | 132 ++++++++++ docs/source/api/physics2d.rst | 51 +++- docs/source/api/physics3d.rst | 19 +- docs/source/api/scene.rst | 56 ++++- docs/source/api/sound.rst | 20 ++ docs/source/api/style.rst | 4 + docs/source/api/tilemap.rst | 430 +++++++++++++++++++++++++++++++++ docs/source/api/time.rst | 49 ++++ docs/source/api/tween.rst | 21 ++ docs/source/index.rst | 4 + 14 files changed, 1428 insertions(+), 6 deletions(-) create mode 100644 docs/source/api/animation.rst create mode 100644 docs/source/api/tilemap.rst create mode 100644 docs/source/api/time.rst diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst new file mode 100644 index 0000000..44af670 --- /dev/null +++ b/docs/source/api/animation.rst @@ -0,0 +1,385 @@ +animation +========= + +Api for creating animation + +**It Contains** + - ``animation`` - infomation on a animation + - ``animation.track`` - infomation on how animation tracks + +Animation +######### + +.. lua:class:: animation + + .. code-block:: lua + :caption: How to create a animation + + newAnimation = animation("my animation") + + local ball = { x = 0, y = 3, col = color.red } + + newTrack = newAnimation:addTrack("color", ball, "col") + newAnimation:play() + + -- every frame + newAnimation:update() + + .. lua:attribute:: id: number + + Can get and set an id for an animation + + .. lua:attribute:: name: string + + .. lua:method:: addTrack(trackType[, target, property]) + + Adds a new track to the animation. + + :param trackType: The type of track to play + :type trackType: enum or string + :param target: The table/userdata that contains that animated property + :type target: table or userdata + :param property: The string that direct to the proper target (property name) + :type property: string + + No parameter: + + :return: A new animation track + :rtype: animation.track + + `The Track Types:` + + * ``animation.track.boolean`` - boolean track + * ``animation.track.number`` - number track + * ``animation.track.vec2`` - vec2 track + * ``animation.track.vec3`` - vec3 track + * ``animation.track.vec4`` - vec4 track + * ``animation.track.color`` - color track + * ``animation.track.quat`` - quat track + * ``animation.track.sprite`` - sprite track + * ``animation.track.sound`` - sound track + * ``animation.track.function`` - function track: calls a function at a the time + * ``animation.track.animationClip`` - animationClip track: plays other animations as a key frame + + .. lua:method:: removeTrack(trackIndex) + + Remove track from a list + + :param trackIndex: the index order that track is in the animation + :type trackIndex: number + + .. lua:method:: update([timeElapsed]) + + Updates that animation based on ``time.elapsed`` or custom elapsed time + + :param timeElapsed: optional parameter to play the animation at a custom time. + :type timeElapsed: number + + .. lua:method:: play() + + Start to plays the animation + + .. lua:method:: pause() + + Pauses the animation + + .. lua:method:: pause() + + Pauses the animation + + .. lua:method:: restart([shouldPlay = true]) + + Restarts the animation from the beginning + + :param shouldPlay: Whether the animation should start playing + :type shouldPlay: boolean + + .. lua:attribute:: playing: boolean + + Checks if the animation is playing + + .. lua:attribute:: tracks: table + + Allow one to get and set tracks for the animation + + .. lua:attribute:: duration: number + + Can get the duration of an animation + + .. lua:attribute:: time: number + + Can get and set the time past through the animation + + .. lua:method:: loop(loopAmount) + + Sets the amount of times the animation loop (once it is done the animation will stop) + + :param loopAmount: How many times the animation loops + :type loopAmount: number + + Set to ``animation.infiniteLoop`` for an infinite loop + + If no parameter: + + :return: The loop amount + :rtype: number + + .. lua:method:: onComplete(onCompleteFunction) + + Set the function that is called when animation is complete + + :param onCompleteFunction: The function to call + :type onCompleteFunction: function() + + If no parameter: + + :return: The function that was inputed before + :rtype: function() + + .. lua:method:: bundle(animation1, ... , animationX) + + Groups multiple animations into one animaiton so they can be played synchronously using the same time. + Each animation gets their own track (``type: animationClip``). + At the front of the track (0 second), an animation clip key frame is place with each animation as a animation clip. + + `Note that duration of the bundled animation is the length of the longest animation` + + :param animation1: A single animation to be added to the bundle + :type animation1: animation + + :return: A new animation able to play all the animations synchronously + :rtype: animation + +Animation Track +############### + +.. lua:class:: animation.track + + .. code-block:: lua + :caption: How to create a animation.track + + ballColorAnimation = animation("ball color animation") + + local ball = { x = 0, y = 3, col = color.red, image = asset.ball1 } + + -- animate ball color + colorTrack = ballColorAnimation:addTrack("color", ball, "col") + + -- Set the key frames of the ball + colorTrack:setKey(0.0, color.red):ease("quadratic", "inout", 1) + colorTrack:setKey(1.0, color.blue):ease("hold") + colorTrack:setKey(2.0, color.green) + + colorTrack[1.0]:value(color.magenta) -- change blue to magenta + + ballSpriteAnimation = animation("ball sprite animation") + + -- animate ball sprite with frames + spriteTrack = ballAnimation:addTrack("sprite", ball, "image") + spriteTrack.frames = {asset.ball1, asset.ball2, asset.ball3} + spriteTrack.fps = 4 + + groupAnimation = animaiton.bundle(ballColorAnimation, ballSpriteAnimation) + spriteAnimationTrack = groupAnimation.tracks[2] -- get the second track + local theDuration = spriteAnimationTrack:keyAt(1):keyInfo("duration") -- get first keyframe + spriteAnimationTrack:keyInfo("duration", theDuration * 3) -- make sprite animation loop 3 times + + groupAnimation:play() + + -- every frame + groupAnimation:update() + + .. lua:attribute:: type: trackType + + What type of track this track is (enums are located in ``animation``) + + .. lua:attribute:: target: table/userdata + + The table/userdata that contains that animated property + + .. lua:attribute:: property: string + + The string that direct to the proper target (property name) + + .. lua:attribute:: duration: number + + The duration of the track which is the last key frame's time, in seconds, plus its duration (most of the time being 0) + + .. lua:attribute:: fps: integer + + The frames one can place pre second + + .. lua:attribute:: timeDelta: number + + Gap of time each frame must be placed. + + .. lua:attribute:: frames: table + + A way to quickly get/set the keyframes for a sprite track (``type = animation.track.sprite``). It uses the timeDelta as a way to space out the sprites + + .. lua:method:: adjustFrames() + + If the timeDelta/fps gets changed this method will adjust all the frames to fit the new fps + + .. lua:attribute:: count: integer + + The amount of keyframes in a track + + + **Below is how KeyFrames work in Codea** + + The way keyframes work is by chaining functions. You create the a key frame but it returns this track but the program set the last + created key frame as the selected keyframe for future functions + + .. lua:method:: setKey(time, value) + + This is the function is add a keyframe to the track it can also replace old values of a previous time. + + :param time: The time of the key frame + :type time: number + :param value: The value of the key frame. If ``trackType = animation.track.vec2`` then value should be a ``vec2``. Every type follow this rule. + :type value: any type + + `Note the a function track takes a string as the parameter representing the name of the funciton. If the track type is a entity it will call dispatch` + + :return: Self to continue function chaining + :rtype: animation.track + + .. lua:method:: [index] (time) + + Select the key frame at this time as the selected keyframe for chaining + + :param time: The time of the key frame + :type time: number + + :return: Self to continue function chaining + :rtype: animation.track + + .. lua:method:: keyAt(keyIndex) + + Select the key frame at this index + + :param keyIndex: The index of the keyframe in the track keyframe list + :type keyIndex: integer + + :return: Self to continue function chaining + :rtype: animation.track + + **The below functions apply to Keyframes created/set above** + + .. lua:method:: time([newTime]) + + Changes the time of the keyframe + + `Note: This method might change the key frames index in the list` + + :param newTime: The new time of the key frame + :type newTime: number + + If there is a parameter than continue function chaining. Else: + + :return: The time of this key frame + :rtype: number + + .. lua:method:: value([newValue]) + + Changes the value of the keyframe + + :param newValue: The new value of the key frame + :type newValue: any type + + If there is a parameter than continue function chaining. Else: + + :return: The value of this key frame + :rtype: value type + + .. lua:method:: delete() + + Deletes the selected key frame from the list + + .. lua:method:: keyInfo (infoName[, infoValue]) + + Gives access to extra infomation about the key frame + + :param infoName: The new value of the key frame + :type infoName: string + + :param infoValue: The new value of the infomation above + :type infoValue: info value type + + If infoValue is not nil than continue function chaining. Else: + + :return: The infomation of that key frame + :rtype: info value type + + `Info Names:` + + * ``"duration"`` - give the duration of the keyframe for sound and animation clip key frames + * ``"startTime"`` - gives the start time (offset) of sound and animation clip + * ``"originalDuration"`` - (Getter) gets the original duration of sound and animation clip + + .. lua:method:: restoreDuration() + + Resets the duration of the selected key frame (sound or animation clip) to it original duration + + .. lua:method:: ease([easingName, easingMode, easeStrength/easeLoopAmount]) + + Quick way to set the easing of the Key Frame (easingName and easingMode can be a string representing the last part of the enum name) + + :param easingName: A enum that represent the name of the the easing + :type easingName: enum + + :param easingMode: A enum that represent the way the easing behaviors + :type easingMode: enum + + :param easeStrength/easeLoopAmount: Represents the strength of the easing curve or if the easing is ``animation.easing.loop`` it the amount of previous key frames that should be looped + :type easeStrength/easeLoopAmount: number + + If there is a parameter than continue function chaining. Else: + + :return: The easingName, easingMode, and easingStrength + :rtype: enum, enum, number + + `Easing Names:` + + * ``animation.easing.linear`` - From a to b it goes a linear speed + * ``animation.easing.quadratic`` - From a to b it goes a quadratic speed + * ``animation.easing.cubic`` - From a to b it goes a cubic speed + * ``animation.easing.quartic`` - From a to b it goes a quartic speed + * ``animation.easing.quintic`` - From a to b it goes a quintic speed + * ``animation.easing.elastic`` - From a to b it goes a elastic speed + * ``animation.easing.exponential`` - From a to b it goes a exponential speed + * ``animation.easing.sine`` - From a to b it goes a sine speed + * ``animation.easing.circular`` - From a to b it goes a circular speed + * ``animation.easing.back`` - From a to b it goes a back speed + * ``animation.easing.hold`` - Hold the current key frame until the next one + * ``animation.easing.loop`` - Loops this key frame and a number previous key frames until the next key frame + + `Easing Mode:` + + * ``animation.easing.in`` - ease in the key frame + * ``animation.easing.out`` - ease out the key frame + * ``animation.easing.inout`` - ease in and ease out the key frame + + .. lua:method:: easeInfo (infoName[, infoValue]) + + Gives access to extra infomation of the easing of the selected key frame + + :param infoName: The new value about the easing of the selected key frame + :type infoName: string + + :param infoValue: The new value of the infomation above + :type infoValue: info value type + + If infoValue is not nil than continue function chaining. Else: + + :return: The infomation of that key frame + :rtype: info value type + + `Info Names:` + + * ``"name"`` - Change the easing name (enum) + * ``"mode"`` - Change the easing mode (enum) + * ``"strength"`` - Change the strength of the easing + * ``"loopAmount"`` - Change the amount of previous frames needing to loop + diff --git a/docs/source/api/entity.rst b/docs/source/api/entity.rst index 01fdeb6..a04b5b1 100644 --- a/docs/source/api/entity.rst +++ b/docs/source/api/entity.rst @@ -51,6 +51,10 @@ entity .. literalinclude:: /code/Example_entity_destroy.codea/Main.lua :language: lua + .. lua:method:: destroyChildren() + + Destroys all the children of an entity + **Components** .. lua:method:: add(component, ...) @@ -428,6 +432,16 @@ entity Callback for the `destroyed()` event, which is called right before the entity is destroyed + **Activation Callbacks** + + .. lua:attribute:: activated: function + + Callback for the ``activated()`` event, which is called when ``entity.active`` is set to true + + .. lua:attribute:: deactivated: function + + Callback for the ``deactivated()`` event, which is called when ``entity.active`` is set to false + **Physics Callbacks** .. lua:attribute:: collisionBegan2d: function @@ -461,3 +475,7 @@ entity Enables hit testing for the ``touched(touch)`` event, which will filter touches based on collision checks using attached physics components on the main camera + .. lua:attribute:: touchPriority: number [default = 0] + + Sets the priority of entity in ``touched(touch)`` event + diff --git a/docs/source/api/graphics.rst b/docs/source/api/graphics.rst index 3997499..cb0b7f1 100644 --- a/docs/source/api/graphics.rst +++ b/docs/source/api/graphics.rst @@ -259,6 +259,24 @@ Text :return: The ``width`` and ``height`` of the text :rtype: number, number +.. lua:function:: textGlyphBounds(str, pos[, size]) + + (Experimental subject to change) Gets the bound each characters in a text + + :param str: The text to query + :type str: string + :param pos: The position of the textbox + :type width: vec2 + :param size: The size of the textbox + :type width: vec2 + :return: The ``width`` and ``height`` of the text + :rtype: glyphBounds + + * ``x`` - x pos of glyph + * ``y`` - y pos of glyph + * ``width`` - width of glyph + * ``height`` - height of glyph + Gizmos ###### @@ -266,10 +284,107 @@ Gizmos are useful for drawing shapes in 2D/3D space for debugging and editing .. lua:module:: gizmos -.. lua:function:: line(x1, y1, z1, x2, y2, z2) +.. lua:function:: line(point1 , point2) Draws a 3D antialiased line + :param point1: First point of line + :type point1: vec3 + :param point2: Second point of line + :type point2: vec3 + +.. lua:function:: box(pos, size) + + Draws a 3D antialiased cube + + :param pos: Position of the box + :type pos: vec3 + :param size: Size of the box + :type size: vec3 + +.. lua:function:: sphere(pos,[ radius = 1, segments = 32]) + + Draws a 3D antialiased sphere + + :param pos: Position of the sphere + :type pos: vec3 + :param radius: Radius of the sphere + :type radius: number + :param segments: Number of subdivisions that make up the sphere + :type segments: number + +.. lua:function:: circlePlane(pos, normal,[ radius = 1, segments = 32, startAngle = 0, endAngle = 360]) + + Draws a 3D antialiased circle plane + + :param pos: Position of the circle + :type pos: vec3 + :param normal: Normal direction of the circle + :type normal: vec3 + :param radius: Radius of the circle + :type radius: number + :param segments: Number of subdivisions that make up the circle + :type segments: number + :param startAngle: Start degree of the circle + :type startAngle: number + :param endAngle: End degree of the circle + :type endAngle: number + +.. lua:function:: cylinder(pos,[ radius = 1, height = 1, segments = 32]) + + Draws a 3D antialiased cylinder + + :param pos: Position of the cylinder + :type pos: vec3 + :param radius: Radius of the cylinder + :type radius: number + :param height: Height of the cylinder + :type height: number + :param segments: Number of subdivisions that make up the cylinder + :type segments: number + +.. lua:function:: capsule(pos,[ radius = 1, height = 1, segments = 32]) + + Draws a 3D antialiased capsule + + :param pos: Position of the capsule + :type pos: vec3 + :param radius: Radius of the capsule + :type radius: number + :param height: Height of the capsule + :type height: number + :param segments: Number of subdivisions that make up the capsule + :type segments: number + +.. lua:function:: polyline(points,[ closeShape = false]) + + Draws a 3D antialiased polyline + + :param points: Table of points (vec3) the represent the poly line + :type points: table + :param radius: Should the line be closed (polygon) + :type radius: boolean + +.. lua:function:: mesh(mesh) + + Draws a 3D antialiased mesh + + :param mesh: The mesh object to draw + :type mesh: mesh + +.. lua:function:: icon(camera, iconSprite, pos, size) + + Draws a image in 3D shape facing the camera + + :param camera: The camera object + :type camera: camera + :param iconSprite: The image to be drawn + :type iconSprite: image + :param pos: The position of the image in 3D space + :type pos: vec3 + :param size: The size of the image in 3D space + :type size: number + Color Space ########### diff --git a/docs/source/api/input.rst b/docs/source/api/input.rst index 7a90763..d5a54fd 100644 --- a/docs/source/api/input.rst +++ b/docs/source/api/input.rst @@ -106,6 +106,13 @@ Touches The previous precise location of the touch (if available) + .. lua:function:: cancelTouch(scene) + + Cancels the touch of a scene + + :param scene: The keyCode to query + :type scene: scene + Gestures ######## @@ -469,3 +476,124 @@ Gamepad .. lua:attribute:: up: boolean .. lua:attribute:: down: boolean + +Mouse +######## + +.. lua:currentmodule:: None + +.. lua:class:: mouse + + .. lua:attribute:: active: boolean + + Is there a mouse active + + .. lua:attribute:: connected: function(mouse) + + Callback for when a mouse is connected + + .. lua:attribute:: disconnected: function(mouse) + + Callback for when a mouse is disconnected + + .. lua:attribute:: left: mouse.button + + .. lua:attribute:: middle: mouse.button + + .. lua:attribute:: right: mouse.button + + .. lua:attribute:: scroll: vec2 + + .. lua:attribute:: x: number + + .. lua:attribute:: y: number + + .. lua:attribute:: pos: vec2 + + Return a vec2 of both the x and y position + + .. lua:attribute:: dx: number + + .. lua:attribute:: dy: number + + .. lua:attribute:: deltaX: number + + .. lua:attribute:: deltaY: number + + .. lua:attribute:: delta: vec2 + + Return a vec2 of both dx and dy + + .. lua:attribute:: visible: boolean + + Sets whether the mouse is visible or hidden + + .. lua:attribute:: pressed: function(mouseName) + + Callback for when the mouse is pressed + + :param mouseName: return the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + + .. lua:attribute:: released: function(mouseName) + + Callback for when the mouse is released + + :param mouseName: return the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + + .. lua:attribute:: changed: function(mouseName, changeState) + + Callback for when the mouse has been changed + + :param mouseName: Returns the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + :param changeState: Inputs true if the mouse was pressed or false if the mouse was released + :type wasPressed: boolean + + .. lua:attribute:: moved: function(deltaX, deltaY) + + Callback for when the mouse has been moved + + :param deltaX: The delta x of the mouse + :type deltaX: number + :param deltaY: The delta y of the mouse + :type deltaY: number + + .. lua:class:: button + + .. lua:attribute:: pressing: boolean + + .. lua:attribute:: pressed: boolean + + .. lua:attribute:: released: boolean + + .. lua:attribute:: value: number + + .. lua:attribute:: touching: boolean + +.. lua:module:: mouse + +.. lua:function:: default() + + Changes the mouse back to its default style + +.. lua:function:: path(polygon1, polygon...) + + Turns the mouse style to a path (allows multiple polygons for unique shapes) + + :param polygon1: Table that represents point of the mouse shape (offset from the mouse) + :type polygon1: table + :param polygon...: for more polygons + :type polygon...: table + +.. lua:function:: rect(pos, size [, roundedRadius = 0]) + + Turns the mouse style to a rectangle + + :param pos: Represents the positions of the rectangle from the mouse + :type pos: vec2 + :param size: Represents the size of the rectangle + :type size: vec2 + :param roundedRadius: Radius of the rectangle + :type roundedRadius: number \ No newline at end of file diff --git a/docs/source/api/math_types.rst b/docs/source/api/math_types.rst index 5ad7235..539ac6a 100644 --- a/docs/source/api/math_types.rst +++ b/docs/source/api/math_types.rst @@ -518,3 +518,135 @@ Axis-Aligned Bounding Box (AABB) .. lua:module:: bounds .. lua:class:: aabb + + .. lua:attribute:: min: vec3 + + .. lua:attribute:: max: vec3 + + .. lua:attribute:: size: vec3 + + Size of the bounding box + + .. lua:attribute:: offect: vec3 + + Offset of the bounding box + + .. lua:attribute:: valid: boolean + + Checks if the bounding box is valid + + .. lua:method:: set(min, max) + + :param min: The minimum position of the bounding box + :type min: vec3 + :param max: The maximum position of the bounding box + :type max: vec3 + + .. lua:method:: translate(amount) + + :param amount: The amount to move the bounding box + :type amount: vec3 + + .. lua:method:: transform(transformMatrix) + + :param transformMatrix: The matrix used to transform the current matrix + :type transformMatrix: mat4 + :return: New bounds to fit the transformed bound + :rtype: aabb + + .. lua:method:: encapsulate(point) + + Adjust the bound to fit a point + + :param point: The point you want to fit + :type point: vec3 + + .. lua:method:: encapsulate(otherAABB) + + Adjust the bound to fit another bound + + :param otherAABB: The aabb you want to fit + :type otherAABB: aabb + + .. lua:method:: raycast(origin, dir) + + :param origin: The position of the ray + :type origin: vec3 + :param dir: The direction of the ray + :type dir: mat4 + :return: The hit infomation of the raycast + :rtype: hit + +.. lua:class:: hit + + .. lua:attribute:: point: vec3 + + The position where the raycast hit + + .. lua:attribute:: normal: vec3 + + The normal of the point hit + +Math Extensions +############### + +.. lua:currentmodule:: None + +.. lua:class:: math + + The following are extensions to the Lua math class. + + .. lua:method:: lerp(a, b, t) + + :param a: The first point + :type a: number + :param b: The second point + :type b: number + :param t: Value between 0 and 1 to represent the progress between a and b + :type t: number + :return: The value that is t% between a and b + :rtype: number + + .. lua:method:: inverseLerp(a, b, v) + + Give the t (progress) value that v is in a and b + + :param a: The first point + :type a: number + :param b: The second point + :type b: number + :param v: Value between a and b + :type v: number + :return: The t (progress) that v is between a and b + :rtype: number + + .. lua:method:: sign(value) + + if value < 0 then -1, if value == 0 then 0, if value > 0 then 1 + + :param value: The value to take the sign of + :type value: number + :return: The sign of the value + :rtype: number + + .. lua:method:: clamp(value, a, b) + + Give the clamp value between a and b, value less than `a` the function outputs `a` and value greater than `b` the function outputs `b` + + :param value: The value to clamp + :type value: number + :param a: The left end of the clamp + :type a: number + :param b: The right end of the clamp + :type b: number + :return: The t (progress) that v is between a and b + :rtype: number + + .. lua:method:: clamp01(value) + + Clamp value between 0 and 1 + + :param value: The value to clamp + :type value: number + :return: The clamped value + :rtype: number \ No newline at end of file diff --git a/docs/source/api/physics2d.rst b/docs/source/api/physics2d.rst index 83d9491..36b2b48 100644 --- a/docs/source/api/physics2d.rst +++ b/docs/source/api/physics2d.rst @@ -363,6 +363,26 @@ Collision The body this collider belongs to + .. lua:method:: collide(otherCollider) + + Checks the collision between two colliers: this one and another collider and gives infomation about it + + :param otherCollider: The other collider to collide with + :type otherCollider: collider + + :return: ``didCollide[, point, normal, penetration]`` - `didCollide` is whether the collision happened + :rtype: boolean[, vec2, vec2, number] + + .. lua:method:: overlap(otherCollider) + + Checks overlapping between two colliers: this one and another collider + + :param otherCollider: The other collider to overlap with + :type otherCollider: collider + + :return: Checks whether the two colliders are overlapping + :rtype: boolean + .. lua:class:: circle: collider .. lua:attribute:: radius: number @@ -438,6 +458,14 @@ Collision The second collider involved in this collision contact + .. lua:attribute:: entity: entity + + The first entity in this contact (the entity receiving the callback) + + .. lua:attribute:: otherEntity: entity + + The second entity involved in this collision contact + .. lua:class:: rayHit .. lua:attribute:: point: vec2 @@ -638,4 +666,25 @@ Constraints .. lua:class:: motor: joint - *Not implemented yet* \ No newline at end of file + *Not implemented yet* + +Settings +######## + +.. lua:class:: settings + + .. lua:attribute:: debugDraw: boolean + + Draws physics objects in the scene + + .. lua:attribute:: gravity: vec2 + + Changes the gravity of the physics world + + .. lua:attribute:: velocityIterations: number + + .. lua:attribute:: positionIterations: number + + .. lua:attribute:: paused: boolean + + Whether you want to paused the physics in a scene \ No newline at end of file diff --git a/docs/source/api/physics3d.rst b/docs/source/api/physics3d.rst index 238110e..63a0817 100644 --- a/docs/source/api/physics3d.rst +++ b/docs/source/api/physics3d.rst @@ -423,4 +423,21 @@ physics3d .. lua:attribute:: body: physics3d.body - The body of the collider that was hit by the ray \ No newline at end of file + The body of the collider that was hit by the ray + +Settings +######## + +.. lua:class:: settings + + .. lua:attribute:: debugDraw: boolean + + Draws physics objects in the scene + + .. lua:attribute:: gravity: vec3 + + Changes the gravity of the physics world + + .. lua:attribute:: paused: boolean + + Whether you want to paused the physics in a scene \ No newline at end of file diff --git a/docs/source/api/scene.rst b/docs/source/api/scene.rst index 67ae2b1..95b975c 100644 --- a/docs/source/api/scene.rst +++ b/docs/source/api/scene.rst @@ -49,6 +49,18 @@ scene Gets the scene's 3D physics world, providing access to various physics functions and properties such as :lua:meth:`physics3d.world.applyForce` + .. lua:attribute:: physics2d: physics2d.settings + + Gets the scene's 2D physics settings, providing access to various physics functions and properties such as :lua:meth:`physics2d.settings.debugDraw` + + .. lua:attribute:: physics3d: physics3d.settings + + Gets the scene's 3D physics settings, providing access to various physics functions and properties such as :lua:meth:`physics3d.settings.debugDraw` + + .. lua:attribute:: time: time.settings + + Gets the scene's time settings, providing access to various time functions and properties such as :lua:meth:`time.settings.autoUpdate` + .. lua:attribute:: sky Sets the sky visuals, which will depend on the type used: @@ -94,13 +106,51 @@ scene :rtype: entity - .. lua:method:: entities([activeOnly = true]) + .. lua:method:: entities([includeFlag = scene.DEFAULT]) - Returns a table containing all root entities + Returns a table containing entities in the scene - :param activeOnly: When set, returns only active root entities + :param includeFlag: Flag to include certain entities. :rtype: table + * ``scene.DEFAULT`` - only active entities *not including the children* + * ``scene.INACTIVE`` - include inactive entities + * ``scene.CHILDREN`` - include all the children and sub childrens of the entities + * ``scene.ALL`` - include all entities in the scene: ``scene.INACTIVE | scene.CHILDREN`` + + .. code-block:: lua + :caption: Getting all the entities + + scen = scene.default2d("test") + + enti = scen:entity("enti") + childEnti = enti:child("childEnti") + + otherEnti = scen:entity("otherEnti") + otherEnti.active = false + + -- include only enti (you could input scene.DEFAULT in parameter for same result) + entityList1 = scen:entities() + + -- include only enti and childEnti + entityList2 = scen:entities(scene.CHILDREN) + + -- include only enti and otherEnti (no children included) + entityList2 = scen:entities(scene.INACTIVE) + + -- loop over all entities in the scene (can use scene.ALL instead) + scen:forEach(function(currentEnti) + print(currentEnti.name) + end, scene.INACTIVE | scene.CHILDREN) + + .. lua:method:: forEach(loopFunction, [includeFlag = scene.DEFAULT]) + + Inputs a callback to that is called while looping over entities in the scene + + :param loopFunction: Function to loop over + :type loopFunction: function(entity) + :param includeFlag: Flag to include certain entities. + .. lua:method:: index(name) [metamethod] Returns the root entity with the given name (if it exists) diff --git a/docs/source/api/sound.rst b/docs/source/api/sound.rst index 752fd52..badcb52 100644 --- a/docs/source/api/sound.rst +++ b/docs/source/api/sound.rst @@ -98,6 +98,10 @@ The sound module provides a way to play and manage sound effects and background .. lua:attribute:: length: number [readonly] Gets the length of this sound source (in seconds) + + .. lua:attribute:: key: assetKey + + The asset key for this sound (if it has one) .. lua:class:: instance @@ -125,6 +129,22 @@ The sound module provides a way to play and manage sound effects and background Get/set the current time of the sound instances play head (in seconds) + .. lua:attribute:: samplerate: number + + Get the samplerate of the sound instance + + .. lua:attribute:: amplitude: number + + Get the amplitude of the sound instance at the current time + + .. lua:attribute:: wave: table + + Get the wave data of the sound instance at the current time + + .. lua:attribute:: fft: table + + Get the fft data of the sound instance at the current time + .. lua:method:: stop Stop the sound instance from playing \ No newline at end of file diff --git a/docs/source/api/style.rst b/docs/source/api/style.rst index 67f89fb..d18ddc5 100644 --- a/docs/source/api/style.rst +++ b/docs/source/api/style.rst @@ -420,6 +420,10 @@ Used by drawing commands and shaders to control stencil operations Text Style ########## +.. lua:function:: font(assetKey) + + Adds a custom font in Codea using it's asset key + .. lua:function:: fontSize(size) .. lua:function:: textAlign(align) diff --git a/docs/source/api/tilemap.rst b/docs/source/api/tilemap.rst new file mode 100644 index 0000000..459dca3 --- /dev/null +++ b/docs/source/api/tilemap.rst @@ -0,0 +1,430 @@ +tilemap +======= + +Api for creating tile maps + +**It Contains** + - ``tm.tiles`` - infomation on a single tile + - ``tm.ruleset`` - infomation on how sprites should behavior in a tile + - ``tm.tileset`` - collection of tiles used in the scene + - ``tm.layer`` - the placement of tiles in the single layer + - ``tm.tilemap`` - the grouping of tilemap layers to draw to the scene + +.. lua:module:: tm + +Tile +#### + +.. lua:class:: tile + + .. code-block:: lua + :caption: How to use tile + + myTileset = tm.tileset() + + newTile = myTileset:tile() + + newTile:sprite(asset.dirtTile):group(7):collision(tm.collision.square) + :ruleset(myRuleSet) + + spriteImg = newTile:sprite() + theRuleset = newTile:ruleset() + + .. lua:attribute:: id: number + + .. lua:method:: sprite([spriteIcon]) + + Set/Get the sprite image of the tile + + :param spriteIcon: The image that the tile contains + :type spriteIcon: sprite + + No parameter: + + :return: The sprite image + :rtype: sprite + + .. lua:method:: group(groupNum) + + Set the sprite image of the tile + + :param groupNum: The group number the tile is from + :type groupNum: number + + :return: self for function chaining + :rtype: tile + + .. lua:method:: collision(mode) + + Set the collision mode of the tile + + :param mode: The enum of the collision + :type mode: enum + + :return: self for function chaining + :rtype: tile + + **Collision Mode Enum:** + + * ``tm.collision.none`` - no collision + * ``tm.collision.square`` - for square collision + * ``tm.collision.sprite`` - for sprite collision + + .. lua:method:: ruleset([theRuleset]) + + Set/Get the ruleset of the tile + + :param theRuleset: The ruleset to be applied to the tile + :type theRuleset: tm.ruleset + + No parameter: + + :return: The ruleset of the tile + :rtype: tm.ruleset + +Ruleset +####### + +.. lua:class:: ruleset + + A ruleset is a object to allows the user to determine how the same tiles should a aranged using certain rules. + Having a ruleset simplify the creation of tilemap as common patterns can be set as a rule + + .. lua:method:: rule() + + Creates a rule in the ruleset and select it. Following ruleset functions will apply to this rule. + + :return: self for function chaining. + :rtype: ruleset + + .. lua:method:: [index] (ruleNum) + + Select the rule in the ruleset. Following ruleset functions will apply to this rule. + + :param ruleNum: the index of the rule in the ruleset + :type ruleNum: integer + + :return: self for function chaining + :rtype: ruleset + + **Below happens to rule created above** + + .. lua:method:: sprite([spriteIcon]) + + Set/Get the sprite image of the rule + + :param spriteIcon: The image that the rule contains + :type spriteIcon: sprite + + No parameter: + + :return: One sprite image for regular and a table for `random` + :rtype: sprite or table + + .. lua:method:: random([spriteList]) + + Set the sprite that will be randomly selected (good for dirt tiles) + + :param spriteList: The images that the rule contains + :type spriteList: table + + :return: self for function chaining + :rtype: ruleset + + .. lua:method:: area(row1,... , rowX) + + Set the tile area rule to determine with sprite should be display in the correct spot. The rows must be a old number 3 - 7. Rows and cols should be the same length + + :param rowX: The layout of the tile (sprite) with other tiles + :type spriteList: string + + * ``@`` - center tile + * ` ` - ignore tile (empty space) + * ``=`` - this tile + * ``x`` - not this tile + * ``g`` - tiles of the same group + + .. code-block:: lua + :caption: How to use area + + local wallRules = tm.ruleset() + + wallRules:rule():sprite(setImgAtlas.c4r2) + :area(" = ", + "=@x", + " = ") + + + :return: self for function chaining + :rtype: ruleset + + .. lua:method:: rotate([shouldRotate]) + + Rotates the rule's tile + + :param shouldRotate: Whether the sprite should be rotated + :type shouldRotate: boolean + + :return: self for function chaining + :rtype: ruleset + + .. lua:method:: flip([flipX, flipY]) + + Flips the rule's tile + + :param flipX: flip sprite horizontally + :type flipX: boolean + :param flipY: flip sprite vertically + :type flipY: boolean + + :return: self for function chaining + :rtype: ruleset + + .. lua:method:: collision(mode) + + Set the collision mode of the rule's tile + + :param mode: The enum of the collision + :type mode: enum + + :return: self for function chaining + :rtype: tile + + .. lua:method:: delete() + + Deletes the currently selected rule from the ruleset + + :return: self for function chaining + :rtype: tile + + .. lua:method:: clear() + + Clears all rules from the ruleset + + :return: self for function chaining + :rtype: tile + + .. lua:attribute:: count: number + + Gets the number of rules in ruleset + + +Tileset +####### + +.. lua:class:: tileset + + .. code-block:: lua + :caption: How to created tileset + + myTileset = tm.tileset() + + newTile = myTileset:tile("dirt") + newTile2 = myTileset["dirt"] -- get the tile from the tileset by name + newTile3 = myTileset[newTile.id] -- get the tile from the tileset by its id + + .. lua:method:: tile(tileName) + + Creates a tile in the tileset + + :param tileName: Name of the tile in the tileset + :type tileName: string + + :return: The newly created tile + :rtype: tile + + .. lua:method:: [index] (tileId) + + Select tile from tileset using its id + + :param tileId: The id of the tile. + :type tileId: integer + + :return: Selected tile + :rtype: tile + + .. lua:method:: [index] (tileName) + + Select tile from tileset using its name + + :param tileName: The name of the tile. + :type tileName: string + + :return: Selected tile + :rtype: tile + + .. lua:method:: clear() + + Clears all tiles from the tileset + + :return: self for function chaining + :rtype: tile + + .. lua:attribute:: count: number + + Gets the number of rules in ruleset + +Tilemap +####### + +.. lua:class:: tilemap + + .. code-block:: lua + :caption: How to create a tilemap + + myTileset = tm.tileset() + + myTilemap = tm.tilemap(myTileset) + + .. lua:method:: layer(layerName) + + Creates layer in the tilemap + + :param layerName: Name of the layer in this tilemap + :type layerName: string + + :return: The newly created layer + :rtype: layer + + .. lua:method:: [index] (layerName) + + Select layer from tilemap using its name + + :param layerName: The name of the layer + :type layerName: string + + :return: Selected layer + :rtype: layer + + .. lua:method:: draw() + + Draw all the layers of the tilemap + + .. lua:attribute:: world2d: world2d + + Gets/sets the physics world. + + .. lua:attribute:: tileset: tileset + + Gets/sets the tileset. + +Layer +##### + +.. lua:class:: layer + + .. code-block:: lua + :caption: How to create a layer + + myTileset = tm.tileset() + + myTilemap = tm.tilemap(myTileset) + + layer1 = myTilemap:layer("layer1") + + .. lua:attribute:: id: number + + .. lua:attribute:: id: name + + .. lua:attribute:: offset: vec3 + + Adjust the position of tilemap drawing + + .. lua:method:: origin() + + Position of bottom left tile + + :return: The x, y, and z of the origin + :rtype: number, number, number + + .. lua:method:: size() + + Size of the tilemap from min position to max position + + :return: The x, y, and z of the size + :rtype: number, number, number + + .. lua:method:: clear() + + Clears all tiles from the layer + + .. lua:method:: get(xPos, yPos) + + Get the tileID at this position + + :param xPos: The x position of the tile + :type xPos: number (integer) + :param yPos: The y position of the tile + :type yPos: number (integer) + + :return: The tileId at that position along with it's tileset + :rtype: number, tileset + + `If tile position does not exist then returns` ``tile.invalidID`` + + .. lua:method:: set(xPos, yPos, tileID|theTile) + + set the tile at this position + + :param xPos: The x position of the tile + :type xPos: number (integer) + :param yPos: The y position of the tile + :type yPos: number (integer) + :param tileID|theTile: Can take in a tileID or the tile itself + :type tileID|theTile: number | tile + + .. lua:method:: draw() + + Draw this layer + + .. lua:method:: fill(xPos, yPos, tileID|theTile) + + Fills the tilemap with this tile + + :param tileID|theTile: Can take in a tileID or the tile itself + :type tileID|theTile: number | tile + + .. lua:method:: resize(xSize, ySize) + + Resizes the layer to a new size + + :param xSize: The new width of the layer + :type xSize: number + :param ySize: The new height of the layer + :type ySize: number + + .. lua:method:: visit(callback) + + Goes through all the position of the the layers and calls this function. The callback function's input takes x, y, z, and tileID (the tile at that position) + + :param callback: The function that will be call each position: function(x, y, z, tileID, tileset) + :type callback: function(number, number, number, number, tileset) + + .. lua:method:: worldToTile(xPos, yPos) + + Get the tile position from the world's position + + :param xPos: The x position of the world + :type xPos: number (integer) + :param yPos: The y position of the world + :type yPos: number (integer) + + :return: returns the tile position from world space + :rtype: number, number + + .. lua:method:: tileToWorld(xPos, yPos) + + Get the world position from the tiles's position + + :param xPos: The x position of the tile in layer + :type xPos: number (integer) + :param yPos: The y position of the tile in layer + :type yPos: number (integer) + + :return: returns the world position from tile space + :rtype: number, number + + .. lua:method:: bounds() + + :return: returns bounds of the layer + :rtype: bounds.aabb \ No newline at end of file diff --git a/docs/source/api/time.rst b/docs/source/api/time.rst new file mode 100644 index 0000000..c774732 --- /dev/null +++ b/docs/source/api/time.rst @@ -0,0 +1,49 @@ +time +===== + +.. lua:class:: time + + .. lua:attribute:: delta: number + + The time between the last frame and this frame + + .. lua:attribute:: unscaledDelta: number + + Time delta without being affected by the time scale + + .. lua:attribute:: fixedDelta: number + + Set delta of the program (like setting the fps) + + .. lua:attribute:: elapsed: number + + The time that has past since the program started + + .. lua:attribute:: unscaledElapsed: number + + The time that has past without being affected by the time scale + + .. lua:attribute:: scale: number + + Allowing the scaling of time to speed up or slow down (default is 1) + +Settings +######## + +For the scene time properties + +.. lua:class:: time.settings + + .. lua:attribute:: autoUpdate: boolean + + Set to false prevents the scene from updating, draw, touching automatically (for manual use) + + .. lua:attribute:: maximumTimeStep: number + + .. lua:attribute:: fixedDelta: number + + Set delta of the scene (like setting the fps) + + .. lua:attribute:: scale: number + + Allowing the scaling of time to speed up or slow down (default is 1) \ No newline at end of file diff --git a/docs/source/api/tween.rst b/docs/source/api/tween.rst index fe622a5..ec9faa8 100644 --- a/docs/source/api/tween.rst +++ b/docs/source/api/tween.rst @@ -68,6 +68,20 @@ Procedurally animate values over time, otherwise known as tweening :param easeType: The easing function to use :type easeType: constant + .. lua:method:: ease(easeFunction) + + Sets a custom easing callback for the current tweening segment (created via ``to{}``) + + :param easeCallback: The easing callback to use + :type easeCallback: function(t, from, to) + + .. lua:method:: delay(time) + + Adds a delay to the tween for a certain time + + :param time: Time in seconds to delay the tween + :type easeType: integer + .. lua:method:: loop(count) Sets the loop count for the current tweening segment (created via ``to{}``). Using `nil` for the count will result in an infinite number of loops @@ -122,6 +136,13 @@ Procedurally animate values over time, otherwise known as tweening :param callback: The callback function :type callback: function + .. lua:method:: onSubComplete(callback) + + Sets a callback for each time the tween reach a sub time in the tween + + :param callback: The callback function + :type callback: function + .. lua:method:: seek(percent) Seeks the tween to a specific normalized time (percentage of duration) diff --git a/docs/source/index.rst b/docs/source/index.rst index 09962f2..8ca48b6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -61,6 +61,7 @@ Codea 4 api/camera api/light api/tween + api/time api/ui api/motion api/require @@ -69,11 +70,14 @@ Codea 4 api/file api/physics2d api/physics3d + api/tilemap + api/animation api/pick api/viewer api/device api/storage + Indices and tables ================== From b2e0a6c99cffda643c4ac4e8d78260171a306405 Mon Sep 17 00:00:00 2001 From: Israel Uche Date: Fri, 6 Mar 2026 18:13:03 -0500 Subject: [PATCH 02/21] Changed the Animation doc to new syntax --- docs/source/api/animation.rst | 376 ++++++++++++++++------------------ docs/source/api/tween.rst | 9 +- 2 files changed, 184 insertions(+), 201 deletions(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 44af670..78840a6 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -4,8 +4,11 @@ animation Api for creating animation **It Contains** + - ``animation`` - infomation on a animation - - ``animation.track`` - infomation on how animation tracks + - ``animation.track`` - infomation on how animation tracks work + - ``animation.key`` - infomation on how animation key frames work + - ``animation.easing`` - infomation on how animation easing work Animation ######### @@ -15,15 +18,27 @@ Animation .. code-block:: lua :caption: How to create a animation - newAnimation = animation("my animation") - local ball = { x = 0, y = 3, col = color.red } - newTrack = newAnimation:addTrack("color", ball, "col") + newAnimation = animation(ball) + + newTrack = newAnimation.col -- creates a animation track using the property "col" + newTrack2 = newAnimation:property("y") -- another way to creates a animation track using the property "y" + newAnimation:play() -- every frame newAnimation:update() + + .. lua:method:: constructor (target) + + The constructor of the animation class + + :param target: The target table or userdata of the animation + :type target: table or userdata + + :return: A new animation + :rtype: animation .. lua:attribute:: id: number @@ -31,53 +46,43 @@ Animation .. lua:attribute:: name: string - .. lua:method:: addTrack(trackType[, target, property]) + .. lua:method:: property(propertyName) - Adds a new track to the animation. + Adds a new track to the animation using that property. Type of the track is inferred. - :param trackType: The type of track to play - :type trackType: enum or string - :param target: The table/userdata that contains that animated property - :type target: table or userdata - :param property: The string that direct to the proper target (property name) - :type property: string + :param propertyName: The string that direct to the proper target (property name) + :type propertyName: string - No parameter: - :return: A new animation track :rtype: animation.track - `The Track Types:` + **Unique Property Names** + + * ``"call"`` - creates a function track + * ``"sound"`` - creates a sound track + * ``"clip"`` - creates a animation clip track + + .. lua:method:: [index] (propertyName) - * ``animation.track.boolean`` - boolean track - * ``animation.track.number`` - number track - * ``animation.track.vec2`` - vec2 track - * ``animation.track.vec3`` - vec3 track - * ``animation.track.vec4`` - vec4 track - * ``animation.track.color`` - color track - * ``animation.track.quat`` - quat track - * ``animation.track.sprite`` - sprite track - * ``animation.track.sound`` - sound track - * ``animation.track.function`` - function track: calls a function at a the time - * ``animation.track.animationClip`` - animationClip track: plays other animations as a key frame + Same as function above. You can just index using the property name to add new track - .. lua:method:: removeTrack(trackIndex) + .. lua:method:: removeTrack(trackObj) - Remove track from a list + Removes this track from a list - :param trackIndex: the index order that track is in the animation - :type trackIndex: number + :param trackObj: the track to be removed + :type trackObj: animation.track - .. lua:method:: update([timeElapsed]) + .. lua:method:: update(timeDelta) - Updates that animation based on ``time.elapsed`` or custom elapsed time + Updates the animation based on ``time.delta`` - :param timeElapsed: optional parameter to play the animation at a custom time. - :type timeElapsed: number + :param timeDelta: time.delta + :type timeDelta: number .. lua:method:: play() - Start to plays the animation + Starts to play the animation .. lua:method:: pause() @@ -100,54 +105,49 @@ Animation .. lua:attribute:: tracks: table - Allow one to get and set tracks for the animation + Allow one to get the tracks of the animation .. lua:attribute:: duration: number - Can get the duration of an animation + Gets the duration of an animation .. lua:attribute:: time: number - Can get and set the time past through the animation + Gets/Sets the time elapsed through the animation - .. lua:method:: loop(loopAmount) + .. lua:attribute:: loopAmount: integer - Sets the amount of times the animation loop (once it is done the animation will stop) + Sets the amount of times the animation loop. Set to 0 for an infinite loop - :param loopAmount: How many times the animation loops - :type loopAmount: number + .. lua:attribute:: onComplete: function - Set to ``animation.infiniteLoop`` for an infinite loop + Set the function that is called when animation is completed - If no parameter: + .. lua:method:: group(animation1, ... , animationX) - :return: The loop amount - :rtype: number - - .. lua:method:: onComplete(onCompleteFunction) - - Set the function that is called when animation is complete + Groups multiple animations into one animaiton so they can be played synchronously using the same time. + Each animation gets their own track (``type: animationClip``). + At the front of the track (0 second), an animation clip key frame is place with each animation as a animation clip. - :param onCompleteFunction: The function to call - :type onCompleteFunction: function() + `Note that duration of the grouped animation is the length of the longest animation` - If no parameter: + :param animation1: A single animation to be added to the group + :type animation1: animation - :return: The function that was inputed before - :rtype: function() + :return: A new animation able to play all the animations synchronously + :rtype: animation - .. lua:method:: bundle(animation1, ... , animationX) + .. lua:method:: sequence(animation1, ... , animationX) - Groups multiple animations into one animaiton so they can be played synchronously using the same time. - Each animation gets their own track (``type: animationClip``). - At the front of the track (0 second), an animation clip key frame is place with each animation as a animation clip. + Groups multiple animations into a one animaiton so they can be played in a sequence. + Each animation is place in a singlar track one after another (``type: animationClip``). - `Note that duration of the bundled animation is the length of the longest animation` + `Note that duration of the sequenced animation is the sum of all the animations' duration` - :param animation1: A single animation to be added to the bundle + :param animation1: A single animation to be added to the sequence :type animation1: animation - :return: A new animation able to play all the animations synchronously + :return: A new animation able to play all the animations sequentially :rtype: animation Animation Track @@ -156,42 +156,59 @@ Animation Track .. lua:class:: animation.track .. code-block:: lua - :caption: How to create a animation.track + :caption: How to create a animation.track - ballColorAnimation = animation("ball color animation") + local ball = { x = 0, y = 3, col = color.red, image = asset.ball1 } - local ball = { x = 0, y = 3, col = color.red, image = asset.ball1 } + ballColorAnimation = animation(ball) - -- animate ball color - colorTrack = ballColorAnimation:addTrack("color", ball, "col") - - -- Set the key frames of the ball - colorTrack:setKey(0.0, color.red):ease("quadratic", "inout", 1) - colorTrack:setKey(1.0, color.blue):ease("hold") - colorTrack:setKey(2.0, color.green) - - colorTrack[1.0]:value(color.magenta) -- change blue to magenta + -- animate ball color + colorTrack = ballColorAnimation.col + + -- Set the key frames of the ball + colorTrack + :key(0.0) -- because the value was not inputted the first key's value is set to color.red because that is the current value of "col" + :key(1.0, color.blue, tween.hold) + :key(2.0, color.green) + + + firstKey = colorTrack:keyAtIndex(1) -- get the key at the first index + firstKey.value = color.white + colorTrack:keyAtTime(1.0).value = color.black -- change the key value at time 1.0 from blue to magenta + colorTrack[2.0].value = color.magenta -- another way to get time - ballSpriteAnimation = animation("ball sprite animation") + ballSpriteAnimation = animation(ball) - -- animate ball sprite with frames - spriteTrack = ballAnimation:addTrack("sprite", ball, "image") - spriteTrack.frames = {asset.ball1, asset.ball2, asset.ball3} - spriteTrack.fps = 4 + -- animate ball sprite with frames + spriteTrack = ballAnimation:property("image") -- another way to create a track for the "image" property + spriteTrack:frames({asset.ball1, asset.ball2, asset.ball3}, { loop = 4, fps = 6 }) -- add frames to track make them loop 4 time at 6 fps - groupAnimation = animaiton.bundle(ballColorAnimation, ballSpriteAnimation) - spriteAnimationTrack = groupAnimation.tracks[2] -- get the second track - local theDuration = spriteAnimationTrack:keyAt(1):keyInfo("duration") -- get first keyframe - spriteAnimationTrack:keyInfo("duration", theDuration * 3) -- make sprite animation loop 3 times + groupAnimation = animaiton.bundle(ballColorAnimation, ballSpriteAnimation) + spriteAnimationTrack = groupAnimation.tracks[2] -- get the second track + secondTrackKey = spriteAnimationTrack:keyAtIndex(1) + local theDuration = secondTrackKey.duration -- get first keyframe + secondTrackKey.duration = theDuration * 2 -- make sprite animation loop 2 times - groupAnimation:play() + groupAnimation:play() - -- every frame - groupAnimation:update() + -- every frame + groupAnimation:update() .. lua:attribute:: type: trackType - What type of track this track is (enums are located in ``animation``) + What type of track this track is + + * ``animation.track.boolean`` - boolean track + * ``animation.track.number`` - number track + * ``animation.track.vec2`` - vec2 track + * ``animation.track.vec3`` - vec3 track + * ``animation.track.vec4`` - vec4 track + * ``animation.track.color`` - color track + * ``animation.track.quat`` - quat track + * ``animation.track.sprite`` - sprite track + * ``animation.track.sound`` - sound track + * ``animation.track.function`` - function track: calls a function at a the time + * ``animation.track.animationClip`` - animationClip track: plays other animations as a key frame .. lua:attribute:: target: table/userdata @@ -203,183 +220,148 @@ Animation Track .. lua:attribute:: duration: number - The duration of the track which is the last key frame's time, in seconds, plus its duration (most of the time being 0) + The duration of the track which is the last key frame's time, in seconds, plus its duration .. lua:attribute:: fps: integer - The frames one can place pre second + The frames that are placed pre second .. lua:attribute:: timeDelta: number - Gap of time each frame must be placed. + Gap of time between each frame placed. - .. lua:attribute:: frames: table + .. lua:method:: frames(theFrames[, frameProperties]) A way to quickly get/set the keyframes for a sprite track (``type = animation.track.sprite``). It uses the timeDelta as a way to space out the sprites - .. lua:method:: adjustFrames() + :param theFrames: a table of frames to represent the frames of an the sprite animation + :type theFrames: table - If the timeDelta/fps gets changed this method will adjust all the frames to fit the new fps + :param frameProperties: a table of properties of how the frames should behave + :type frameProperties: table - .. lua:attribute:: count: integer + * ``"delta"`` - sets the space of time each frame should be placed. For example: 0.1 (this would space the frames but every 0.1 seconds) + * ``"fps"`` - another way of doing delta but sets the fps of the sprites + * ``"loop"`` - amount of times the sprites should loop - The amount of keyframes in a track + .. lua:method:: adjustFrames() + If the timeDelta/fps gets changed this method will adjust all the frames to fit the new timeDelta/fps - **Below is how KeyFrames work in Codea** + .. lua:attribute:: count: integer - The way keyframes work is by chaining functions. You create the a key frame but it returns this track but the program set the last - created key frame as the selected keyframe for future functions + The amount of keyframes in a track - .. lua:method:: setKey(time, value) + .. lua:method:: key(time[, value, properties]) - This is the function is add a keyframe to the track it can also replace old values of a previous time. + This is the function to add a keyframe to the track. (Does Chaining) :param time: The time of the key frame :type time: number - :param value: The value of the key frame. If ``trackType = animation.track.vec2`` then value should be a ``vec2``. Every type follow this rule. + :param value: The value of the key frame. If ``trackType = animation.track.vec2`` then value should be a ``vec2``. Every type follow this rule. If there is no value then set to current value of ``target[property]`` :type value: any type - - `Note the a function track takes a string as the parameter representing the name of the funciton. If the track type is a entity it will call dispatch` + :param properties: Quick way to add properties of key + :type properties: table or easing enum - :return: Self to continue function chaining - :rtype: animation.track + **Possible properties** - .. lua:method:: [index] (time) + `If easing enum` - Select the key frame at this time as the selected keyframe for chaining + Set the easing. Examples: ``tween.cubicIn`` or ``tween.hold`` - :param time: The time of the key frame - :type time: number + `If table:` - :return: Self to continue function chaining - :rtype: animation.track + * ``"ease"`` - Sets the ease type of the key frame (``type: tween enum``) + * ``"strength"`` - Sets the strength of the easing (``type: number``) + * ``"loop"`` - Sets the amount of previous keys to be looped (``type: integer``) - .. lua:method:: keyAt(keyIndex) + `If table but type of track is sound or animation clip` - Select the key frame at this index + * ``"duration"`` - Sets the duration of the key frame (``type: number``) + * ``"start"`` - Sets the start time of the key frame (``type: number``) - :param keyIndex: The index of the keyframe in the track keyframe list - :type keyIndex: integer - :return: Self to continue function chaining - :rtype: animation.track + .. lua:method:: keyAtIndex(keyIndex) - **The below functions apply to Keyframes created/set above** + Returns the key frame at this index - .. lua:method:: time([newTime]) + :param keyIndex: The index of the keyframe in the track keyframe list + :type keyIndex: integer - Changes the time of the keyframe + :return: Key at that index + :rtype: animation.key - `Note: This method might change the key frames index in the list` + .. lua:method:: keyAtTime(time) - :param newTime: The new time of the key frame - :type newTime: number + Returns the key frame at this time - If there is a parameter than continue function chaining. Else: + :param time: The time of the key frame + :type time: number - :return: The time of this key frame - :rtype: number + :return: Key at that time + :rtype: animation.key - .. lua:method:: value([newValue]) + .. lua:method:: [index] (time) - Changes the value of the keyframe + Does the same thing as ``keyAtTime`` - :param newValue: The new value of the key frame - :type newValue: any type +Animation Key +############# - If there is a parameter than continue function chaining. Else: +.. lua:class:: animation.key - :return: The value of this key frame - :rtype: value type + .. lua:attribute:: time: number - .. lua:method:: delete() + Changes the time of the keyframe - Deletes the selected key frame from the list + `Note: This method might change the key frames index in the list` - .. lua:method:: keyInfo (infoName[, infoValue]) + .. lua:attribute:: value: number - Gives access to extra infomation about the key frame + Changes the value of the keyframe - :param infoName: The new value of the key frame - :type infoName: string + .. lua:attribute:: duration: number - :param infoValue: The new value of the infomation above - :type infoValue: info value type + Changes the duration of the keyframe for sound and animation clip key frames - If infoValue is not nil than continue function chaining. Else: + .. lua:attribute:: startTime: number - :return: The infomation of that key frame - :rtype: info value type + Changes the start time (offset) of sound and animation clip - `Info Names:` + .. lua:attribute:: originalDuration: number - * ``"duration"`` - give the duration of the keyframe for sound and animation clip key frames - * ``"startTime"`` - gives the start time (offset) of sound and animation clip - * ``"originalDuration"`` - (Getter) gets the original duration of sound and animation clip + Gets the original duration of sound or animation clip .. lua:method:: restoreDuration() - Resets the duration of the selected key frame (sound or animation clip) to it original duration + Resets the duration of this key frame (sound or animation clip) to it original duration - .. lua:method:: ease([easingName, easingMode, easeStrength/easeLoopAmount]) - - Quick way to set the easing of the Key Frame (easingName and easingMode can be a string representing the last part of the enum name) - - :param easingName: A enum that represent the name of the the easing - :type easingName: enum - - :param easingMode: A enum that represent the way the easing behaviors - :type easingMode: enum - - :param easeStrength/easeLoopAmount: Represents the strength of the easing curve or if the easing is ``animation.easing.loop`` it the amount of previous key frames that should be looped - :type easeStrength/easeLoopAmount: number - - If there is a parameter than continue function chaining. Else: - - :return: The easingName, easingMode, and easingStrength - :rtype: enum, enum, number + .. lua:method:: delete() - `Easing Names:` + Deletes this key frame from its parent track list + + .. lua:attribute:: valid: boolean - * ``animation.easing.linear`` - From a to b it goes a linear speed - * ``animation.easing.quadratic`` - From a to b it goes a quadratic speed - * ``animation.easing.cubic`` - From a to b it goes a cubic speed - * ``animation.easing.quartic`` - From a to b it goes a quartic speed - * ``animation.easing.quintic`` - From a to b it goes a quintic speed - * ``animation.easing.elastic`` - From a to b it goes a elastic speed - * ``animation.easing.exponential`` - From a to b it goes a exponential speed - * ``animation.easing.sine`` - From a to b it goes a sine speed - * ``animation.easing.circular`` - From a to b it goes a circular speed - * ``animation.easing.back`` - From a to b it goes a back speed - * ``animation.easing.hold`` - Hold the current key frame until the next one - * ``animation.easing.loop`` - Loops this key frame and a number previous key frames until the next key frame + Checks if the keyframe is still valid - `Easing Mode:` + .. lua:attribute:: easing: animation.easing - * ``animation.easing.in`` - ease in the key frame - * ``animation.easing.out`` - ease out the key frame - * ``animation.easing.inout`` - ease in and ease out the key frame + Gets the easing of this key - .. lua:method:: easeInfo (infoName[, infoValue]) +Animation Easing +################ - Gives access to extra infomation of the easing of the selected key frame +.. lua:class:: animation.easing - :param infoName: The new value about the easing of the selected key frame - :type infoName: string + .. lua:attribute:: type: tween easing enum - :param infoValue: The new value of the infomation above - :type infoValue: info value type + Changes the type of easing of the key frame - If infoValue is not nil than continue function chaining. Else: + .. lua:attribute:: strength: number - :return: The infomation of that key frame - :rtype: info value type + Changes the strength of the easing - `Info Names:` + .. lua:attribute:: loopAmount: integer - * ``"name"`` - Change the easing name (enum) - * ``"mode"`` - Change the easing mode (enum) - * ``"strength"`` - Change the strength of the easing - * ``"loopAmount"`` - Change the amount of previous frames needing to loop + Changes amount of previous frames that are looped diff --git a/docs/source/api/tween.rst b/docs/source/api/tween.rst index ec9faa8..46ad134 100644 --- a/docs/source/api/tween.rst +++ b/docs/source/api/tween.rst @@ -185,9 +185,9 @@ Here is a list of all easing functions * - ``backIn`` * - ``backOut`` * - ``backInOut`` - * - ``bounceIn`` - * - ``bounceOut`` - * - ``bounceInOut`` + * - ``bounceIn`` - only for ``tween`` + * - ``bounceOut`` - only for ``tween`` + * - ``bounceInOut`` - only for ``tween`` * - ``circularIn`` * - ``circularOut`` * - ``circularInOut`` @@ -206,4 +206,5 @@ Here is a list of all easing functions * - ``elasticIn`` * - ``elasticOut`` * - ``elasticInOut`` - * - ``punch`` \ No newline at end of file + * - ``punch`` + * - ``hold`` - only for ``animation.easing`` \ No newline at end of file From 8d8806f8f52df9cf500aa72a8b93a50db99d87eb Mon Sep 17 00:00:00 2001 From: Israel Uche Date: Sun, 8 Mar 2026 21:33:32 -0400 Subject: [PATCH 03/21] Added open key frame and custom funciton documentation --- docs/source/api/animation.rst | 28 ++++++++ docs/source/api/input.rst | 126 ++++++++++++++++++++++++---------- 2 files changed, 119 insertions(+), 35 deletions(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 78840a6..20585aa 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -305,6 +305,34 @@ Animation Track Does the same thing as ``keyAtTime`` + .. lua:method:: custom ([function]) + + This allows this track to use a custom function instead the property to set the target + + :param function: Sets the custom function if no input then use default behavior + :type function: function + + .. code-block:: lua + :caption: How to use custom + + ani:target(boyEntity) + trac = ani.rz -- creates a track of the "rz" (rotation on z axis). + :key(0.0, nil) + :key(1.0, 720.0) + + trac:custom(function(value) -- because setting "rz" is unstable it is safer to set the rotation variable directly so we use a custom function + boy.rotation = quat.eulerAngles(0, 0, value) + end) + + .. lua:attribute:: openBeginning: boolean + + This is a variable that sets the 0 second key frame to be open meaning that the track will add a key frame at 0 second time and will set the value to the current property value. + This can be used to smoothly go from game play to a cut scene without an abrupt cut. + + .. lua:attribute:: openEasing: animation.easing + + This is the easing of the open key frame + Animation Key ############# diff --git a/docs/source/api/input.rst b/docs/source/api/input.rst index d5a54fd..fb55976 100644 --- a/docs/source/api/input.rst +++ b/docs/source/api/input.rst @@ -160,11 +160,35 @@ Gestures The current number of touches associated with this gesture + .. lua:attribute:: direction: enum + + The direction of the swipe + + .. lua:attribute:: left: integer + + Left direction enum + + .. lua:attribute:: right: integer + + Right direction enum + + .. lua:attribute:: up: integer + + Up direction enum + + .. lua:attribute:: down: integer + + Down direction enum + + .. lua:attribute:: all: integer + + All direction enum + .. lua:class:: gesture.tap Tap gesture recognizer (using system gesture recognizer for implementation) - .. lua:staticmethod:: gesture.tap(callback[, minTouches = 1, maxTouches = 1]) + .. lua:staticmethod:: gesture.tap(callback[, tapCount = 1, touchCount = 1]) Creates and registers a new tap gesture recognizer that will call ``callback(gesture)`` when recognized @@ -176,7 +200,7 @@ Gestures Pan gesture recognizer (using system gesture recognizer for implementation) - .. lua:staticmethod:: gesture.pan(callback[, minTouches = 1, maxTouches = 1]) + .. lua:staticmethod:: gesture.pan(callback[, minTouches = 1, maxTouches = 1, trackpadSupport = false]) Creates and registers a new pan gesture recognizer that will call ``callback(gesture)`` when recognized @@ -210,6 +234,32 @@ Gestures Enables/disables this gesture recognizer +.. lua:class:: gesture.swipe + + Swipe gesture recognizer (using system gesture recognizer for implementation) + + .. lua:staticmethod:: gesture.swipe(callback[, swipeDirection = gesture.all, touchCount = 1]) + + Creates and registers a new swipe gesture recognizer that will call ``callback(gesture)`` when recognized + + :return: The gestures in this order (left, right, up, down). But if a direction is not included then it is ingored + :rtype: gesture.swipe, gesture.swipe, gesture.swipe, gesture.swipe + + .. lua:attribute:: enabled: boolean + + Enables/disables this gesture recognizer + +.. lua:class:: gesture.longPress + + Rotation gesture recognizer (using system gesture recognizer for implementation) + + .. lua:staticmethod:: gesture.longPress(callback[, tapCount = 0, touchCount = 1, allowableMovement = 10, minimumPressDuration = 0.5]) + + Creates and registers a new long press gesture recognizer that will call ``callback(gesture)`` when recognized + + .. lua:attribute:: enabled: boolean + + Enables/disables this gesture recognizer Keyboard ######## @@ -528,38 +578,6 @@ Mouse Sets whether the mouse is visible or hidden - .. lua:attribute:: pressed: function(mouseName) - - Callback for when the mouse is pressed - - :param mouseName: return the name of the mouse being selected ("left", "right", "middle") - :type mouseName: string - - .. lua:attribute:: released: function(mouseName) - - Callback for when the mouse is released - - :param mouseName: return the name of the mouse being selected ("left", "right", "middle") - :type mouseName: string - - .. lua:attribute:: changed: function(mouseName, changeState) - - Callback for when the mouse has been changed - - :param mouseName: Returns the name of the mouse being selected ("left", "right", "middle") - :type mouseName: string - :param changeState: Inputs true if the mouse was pressed or false if the mouse was released - :type wasPressed: boolean - - .. lua:attribute:: moved: function(deltaX, deltaY) - - Callback for when the mouse has been moved - - :param deltaX: The delta x of the mouse - :type deltaX: number - :param deltaY: The delta y of the mouse - :type deltaY: number - .. lua:class:: button .. lua:attribute:: pressing: boolean @@ -596,4 +614,42 @@ Mouse :param size: Represents the size of the rectangle :type size: vec2 :param roundedRadius: Radius of the rectangle - :type roundedRadius: number \ No newline at end of file + :type roundedRadius: number + +.. lua:currentmodule:: None + +**Global Mouse Funcitons** + +.. lua:method:: mousePressed(mouseName) + + Function for when the mouse is pressed + + :param mouseName: return the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + +.. lua:method:: mouseReleased(mouseName) + + Function for when the mouse is released + + :param mouseName: return the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + +.. lua:method:: mouseChanged(mouseName, changeState) + + Function for when the mouse has been changed + + :param mouseName: Returns the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + :param changeState: Inputs true if the mouse was pressed or false if the mouse was released + :type wasPressed: boolean + +.. lua:method:: mouseMoved(deltaX, deltaY) + + Function for when the mouse has been moved + + :param deltaX: The delta x of the mouse + :type deltaX: number + :param deltaY: The delta y of the mouse + :type deltaY: number + + From 64617dabfac8af835867dd3292a3de8fa2b5ab00 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:37:08 -0400 Subject: [PATCH 04/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 20585aa..01b9436 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -1,7 +1,7 @@ animation ========= -Api for creating animation +API for creating animation **It Contains** From af1d66e5d0b42c75c5c6088410f8702b59a705b3 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:37:35 -0400 Subject: [PATCH 05/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 01b9436..ce9d669 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -8,7 +8,7 @@ API for creating animation - ``animation`` - infomation on a animation - ``animation.track`` - infomation on how animation tracks work - ``animation.key`` - infomation on how animation key frames work - - ``animation.easing`` - infomation on how animation easing work + - ``animation.easing`` - information on how animation easing work Animation ######### From 91f538faaada8f634559355be3b18505ff4eef16 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:38:00 -0400 Subject: [PATCH 06/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index ce9d669..b5b4437 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -7,7 +7,7 @@ API for creating animation - ``animation`` - infomation on a animation - ``animation.track`` - infomation on how animation tracks work - - ``animation.key`` - infomation on how animation key frames work + - ``animation.key`` - information on how animation key frames work - ``animation.easing`` - information on how animation easing work Animation From 8ddeb9a6f0e41774f11ddc90f5b8839cbd6713a3 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:38:18 -0400 Subject: [PATCH 07/21] Update docs/source/api/tilemap.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/tilemap.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/tilemap.rst b/docs/source/api/tilemap.rst index 459dca3..5f28eef 100644 --- a/docs/source/api/tilemap.rst +++ b/docs/source/api/tilemap.rst @@ -133,7 +133,7 @@ Ruleset .. lua:method:: area(row1,... , rowX) - Set the tile area rule to determine with sprite should be display in the correct spot. The rows must be a old number 3 - 7. Rows and cols should be the same length + Set the tile area rule to determine with sprite should be displayed in the correct spot. The rows must be a old number 3 - 7. Rows and cols should be the same length :param rowX: The layout of the tile (sprite) with other tiles :type spriteList: string From 51bede8fe031a296cfba370aa3135eca62e58fc0 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:39:22 -0400 Subject: [PATCH 08/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index b5b4437..30f2fbf 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -5,7 +5,7 @@ API for creating animation **It Contains** - - ``animation`` - infomation on a animation + - ``animation`` - information on a animation - ``animation.track`` - infomation on how animation tracks work - ``animation.key`` - information on how animation key frames work - ``animation.easing`` - information on how animation easing work From 4ce0a244c1d88320da8097861bde2ffccf1a9253 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:39:33 -0400 Subject: [PATCH 09/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 30f2fbf..b86fca2 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -6,7 +6,7 @@ API for creating animation **It Contains** - ``animation`` - information on a animation - - ``animation.track`` - infomation on how animation tracks work + - ``animation.track`` - information on how animation tracks work - ``animation.key`` - information on how animation key frames work - ``animation.easing`` - information on how animation easing work From a31609fabe9e6f8cdb9a1d18e15c95b4221af172 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:40:06 -0400 Subject: [PATCH 10/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index b86fca2..b0802a9 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -16,7 +16,7 @@ Animation .. lua:class:: animation .. code-block:: lua - :caption: How to create a animation + :caption: How to create an animation local ball = { x = 0, y = 3, col = color.red } From c7e6b22e0da8b27655ac614b0add55b4138e150b Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:40:28 -0400 Subject: [PATCH 11/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index b0802a9..99a1c81 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -23,7 +23,7 @@ Animation newAnimation = animation(ball) newTrack = newAnimation.col -- creates a animation track using the property "col" - newTrack2 = newAnimation:property("y") -- another way to creates a animation track using the property "y" + newTrack2 = newAnimation:property("y") -- another way to create an animation track using the property "y" newAnimation:play() From afd199ce7598a4cd38e9c080bbaec00a7d0886a2 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:40:48 -0400 Subject: [PATCH 12/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 99a1c81..1fb7cea 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -50,7 +50,7 @@ Animation Adds a new track to the animation using that property. Type of the track is inferred. - :param propertyName: The string that direct to the proper target (property name) + :param propertyName: The string that directs to the proper target (property name) :type propertyName: string :return: A new animation track From a4a661e5822b75389066eeb38eb6ecbad8d8ad80 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:41:18 -0400 Subject: [PATCH 13/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 1fb7cea..7c89663 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -42,7 +42,7 @@ Animation .. lua:attribute:: id: number - Can get and set an id for an animation + Get or set the animation's identifier .. lua:attribute:: name: string From b13463850e1d8b07020af33b691812391cd999e3 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:43:32 -0400 Subject: [PATCH 14/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 7c89663..3a324be 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -60,7 +60,7 @@ Animation * ``"call"`` - creates a function track * ``"sound"`` - creates a sound track - * ``"clip"`` - creates a animation clip track + * ``"clip"`` - creates an animation clip track .. lua:method:: [index] (propertyName) From 37acab20f2015e64544f3d979ef0eba1c1f5b228 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:49:18 -0400 Subject: [PATCH 15/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 3a324be..511e57d 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -64,7 +64,7 @@ Animation .. lua:method:: [index] (propertyName) - Same as function above. You can just index using the property name to add new track + Adds a new track by passing the property name as index. .. lua:method:: removeTrack(trackObj) From 4679c525394b97c4a35a2b51137e3c4b63c86da7 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:50:16 -0400 Subject: [PATCH 16/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 511e57d..87197f8 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -68,7 +68,7 @@ Animation .. lua:method:: removeTrack(trackObj) - Removes this track from a list + Removes this track :param trackObj: the track to be removed :type trackObj: animation.track From 6e6524539c604687e12dcb97f7a52aa7e48b7cdf Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 20:50:35 -0400 Subject: [PATCH 17/21] Update docs/source/api/animation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 87197f8..2a03e39 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -75,7 +75,7 @@ Animation .. lua:method:: update(timeDelta) - Updates the animation based on ``time.delta`` + Updates the animation by ``time.delta`` :param timeDelta: time.delta :type timeDelta: number From 62128332fc9e3e3394b7a22255abd0d592b2f3a1 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 21:16:31 -0400 Subject: [PATCH 18/21] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/animation.rst | 66 +++++++++++++++++----------------- docs/source/api/input.rst | 12 +++---- docs/source/api/math_types.rst | 10 +++--- docs/source/api/physics2d.rst | 12 +++---- 4 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 2a03e39..72fad42 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -117,19 +117,19 @@ Animation .. lua:attribute:: loopAmount: integer - Sets the amount of times the animation loop. Set to 0 for an infinite loop + Sets the amount of times the animation loops. Set to 0 for an infinite loop. .. lua:attribute:: onComplete: function - Set the function that is called when animation is completed + Set a function to call when the animation is complete. .. lua:method:: group(animation1, ... , animationX) - Groups multiple animations into one animaiton so they can be played synchronously using the same time. + Groups multiple animations into one animations so they can be played synchronously using the same time. Each animation gets their own track (``type: animationClip``). - At the front of the track (0 second), an animation clip key frame is place with each animation as a animation clip. + At the front of the track (0 second), an animation clip key frame is placed with each animation as an animation clip. - `Note that duration of the grouped animation is the length of the longest animation` + `Note that the duration of the grouped animation is the length of the longest animation.` :param animation1: A single animation to be added to the group :type animation1: animation @@ -139,10 +139,10 @@ Animation .. lua:method:: sequence(animation1, ... , animationX) - Groups multiple animations into a one animaiton so they can be played in a sequence. - Each animation is place in a singlar track one after another (``type: animationClip``). + Groups multiple animations into a single animation so they can be played sequentially. + Each animation is placed in a singlar track one after another (``type: animationClip``). - `Note that duration of the sequenced animation is the sum of all the animations' duration` + `Note that the duration of the sequenced animation is the sum of all the animations' duration.` :param animation1: A single animation to be added to the sequence :type animation1: animation @@ -156,13 +156,13 @@ Animation Track .. lua:class:: animation.track .. code-block:: lua - :caption: How to create a animation.track + :caption: How to create an animation.track local ball = { x = 0, y = 3, col = color.red, image = asset.ball1 } ballColorAnimation = animation(ball) - -- animate ball color + -- Animate the ball's color colorTrack = ballColorAnimation.col -- Set the key frames of the ball @@ -172,7 +172,7 @@ Animation Track :key(2.0, color.green) - firstKey = colorTrack:keyAtIndex(1) -- get the key at the first index + firstKey = colorTrack:keyAtIndex(1) -- get the first key firstKey.value = color.white colorTrack:keyAtTime(1.0).value = color.black -- change the key value at time 1.0 from blue to magenta colorTrack[2.0].value = color.magenta -- another way to get time @@ -181,13 +181,13 @@ Animation Track -- animate ball sprite with frames spriteTrack = ballAnimation:property("image") -- another way to create a track for the "image" property - spriteTrack:frames({asset.ball1, asset.ball2, asset.ball3}, { loop = 4, fps = 6 }) -- add frames to track make them loop 4 time at 6 fps + spriteTrack:frames({asset.ball1, asset.ball2, asset.ball3}, { loop = 4, fps = 6 }) -- add frames to the track and make it loop 4 times at 6 fps - groupAnimation = animaiton.bundle(ballColorAnimation, ballSpriteAnimation) + groupAnimation = animation.bundle(ballColorAnimation, ballSpriteAnimation) spriteAnimationTrack = groupAnimation.tracks[2] -- get the second track secondTrackKey = spriteAnimationTrack:keyAtIndex(1) - local theDuration = secondTrackKey.duration -- get first keyframe - secondTrackKey.duration = theDuration * 2 -- make sprite animation loop 2 times + local theDuration = secondTrackKey.duration -- get first key frame + secondTrackKey.duration = theDuration * 2 -- make the sprite animation loop 2 times groupAnimation:play() @@ -196,7 +196,7 @@ Animation Track .. lua:attribute:: type: trackType - What type of track this track is + Returns this track's type. * ``animation.track.boolean`` - boolean track * ``animation.track.number`` - number track @@ -207,8 +207,8 @@ Animation Track * ``animation.track.quat`` - quat track * ``animation.track.sprite`` - sprite track * ``animation.track.sound`` - sound track - * ``animation.track.function`` - function track: calls a function at a the time - * ``animation.track.animationClip`` - animationClip track: plays other animations as a key frame + * ``animation.track.function`` - function call track + * ``animation.track.animationClip`` - animationClip track: plays another animation .. lua:attribute:: target: table/userdata @@ -216,7 +216,7 @@ Animation Track .. lua:attribute:: property: string - The string that direct to the proper target (property name) + The string that directs to the proper target (property name) .. lua:attribute:: duration: number @@ -228,37 +228,37 @@ Animation Track .. lua:attribute:: timeDelta: number - Gap of time between each frame placed. + Gap of time between each frame played. .. lua:method:: frames(theFrames[, frameProperties]) - A way to quickly get/set the keyframes for a sprite track (``type = animation.track.sprite``). It uses the timeDelta as a way to space out the sprites + A way to quickly get/set the keyframes for a sprite track (``type = animation.track.sprite``). It uses the timeDelta as a way to space out the sprites. - :param theFrames: a table of frames to represent the frames of an the sprite animation + :param theFrames: a table of frames to represent the frames of the sprite animation :type theFrames: table :param frameProperties: a table of properties of how the frames should behave :type frameProperties: table - * ``"delta"`` - sets the space of time each frame should be placed. For example: 0.1 (this would space the frames but every 0.1 seconds) + * ``"delta"`` - sets the space of time each frame should be played. For example: 0.1 (this would space the frames every 0.1 seconds) * ``"fps"`` - another way of doing delta but sets the fps of the sprites - * ``"loop"`` - amount of times the sprites should loop + * ``"loop"`` - number of times the sprites should loop .. lua:method:: adjustFrames() - If the timeDelta/fps gets changed this method will adjust all the frames to fit the new timeDelta/fps + Adjust the frames to fit the new timeDelta/fps. .. lua:attribute:: count: integer - The amount of keyframes in a track + The number of key frames in a track. .. lua:method:: key(time[, value, properties]) - This is the function to add a keyframe to the track. (Does Chaining) + Add a key frame to the track. (supports chaining) :param time: The time of the key frame :type time: number - :param value: The value of the key frame. If ``trackType = animation.track.vec2`` then value should be a ``vec2``. Every type follow this rule. If there is no value then set to current value of ``target[property]`` + :param value: The value of the key frame. If ``trackType = animation.track.vec2`` then value should be a ``vec2``. Every type follows this rule. If there is no value then set to current value of ``target[property]`` :type value: any type :param properties: Quick way to add properties of key :type properties: table or easing enum @@ -307,7 +307,7 @@ Animation Track .. lua:method:: custom ([function]) - This allows this track to use a custom function instead the property to set the target + This allows this track to use a custom function instead of a property to set the target :param function: Sets the custom function if no input then use default behavior :type function: function @@ -326,8 +326,8 @@ Animation Track .. lua:attribute:: openBeginning: boolean - This is a variable that sets the 0 second key frame to be open meaning that the track will add a key frame at 0 second time and will set the value to the current property value. - This can be used to smoothly go from game play to a cut scene without an abrupt cut. + This is a variable that sets the 0 second key frame to be open. When true, the track will add a key frame at 0 second time and set the value to the current property value. + This can be used to smoothly go from gameplay to a cut scene without an abrupt cut. .. lua:attribute:: openEasing: animation.easing @@ -362,7 +362,7 @@ Animation Key .. lua:method:: restoreDuration() - Resets the duration of this key frame (sound or animation clip) to it original duration + Resets the duration of this key frame (sound or animation clip) to its original duration .. lua:method:: delete() @@ -391,5 +391,5 @@ Animation Easing .. lua:attribute:: loopAmount: integer - Changes amount of previous frames that are looped + Changes the amount of previous frames to loop diff --git a/docs/source/api/input.rst b/docs/source/api/input.rst index 53a1f08..fe68ef1 100644 --- a/docs/source/api/input.rst +++ b/docs/source/api/input.rst @@ -229,7 +229,7 @@ Gestures The direction of the swipe - .. helptext:: get the direction for this gesture + .. helptext:: get the direction of the swipe .. lua:attribute:: left: integer @@ -335,7 +335,7 @@ Gestures Creates and registers a new swipe gesture recognizer that will call ``callback(gesture)`` when recognized - :return: The gestures in this order (left, right, up, down). But if a direction is not included then it is ingored + :return: The gestures in this order (left, right, up, down). But if a direction is not included, it is ignored. :rtype: gesture.swipe, gesture.swipe, gesture.swipe, gesture.swipe .. helptext:: create a swipe gesture recognizer @@ -360,7 +360,7 @@ Gestures Enables/disables this gesture recognizer - .. helptext:: whether the gesture recognizer is enabled + .. helptext:: get or set if the gesture recognizer is enabled Keyboard ######## @@ -919,7 +919,7 @@ Mouse .. lua:attribute:: active: boolean - Is there a mouse active + Checks if a mouse is currently active. .. helptext:: checks if a mouse is active @@ -927,13 +927,13 @@ Mouse Callback for when a mouse is connected - .. helptext:: sets a callback to call when a mouse is connected + .. helptext:: callback to call when a mouse is connected .. lua:attribute:: disconnected: function(mouse) Callback for when a mouse is disconnected - .. helptext:: sets a callback to call when a mouse is disconnected + .. helptext:: callback to call when a mouse is disconnected .. lua:attribute:: left: mouse.button diff --git a/docs/source/api/math_types.rst b/docs/source/api/math_types.rst index a9f6bde..094dfcb 100644 --- a/docs/source/api/math_types.rst +++ b/docs/source/api/math_types.rst @@ -800,7 +800,7 @@ Math Extensions :type b: number :param t: Value between 0 and 1 to represent the progress between a and b :type t: number - :return: The value that is t% between a and b + :return: The interpolated value between a and b at ratio t. :rtype: number .. lua:method:: inverseLerp(a, b, v) @@ -813,12 +813,12 @@ Math Extensions :type b: number :param v: Value between a and b :type v: number - :return: The t (progress) that v is between a and b + :return: The ratio from a to b at which the interpolated value is v :rtype: number .. lua:method:: sign(value) - if value < 0 then -1, if value == 0 then 0, if value > 0 then 1 + Returns -1 if value < 0, 0 if value == 0, 1 if value > 0. :param value: The value to take the sign of :type value: number @@ -827,7 +827,7 @@ Math Extensions .. lua:method:: clamp(value, a, b) - Give the clamp value between a and b, value less than `a` the function outputs `a` and value greater than `b` the function outputs `b` + Clamp the value between `a` and `b`. If the value is less than `a`, the function outputs `a`. If the value is greater than `b`, the function outputs `b`. Returns value otherwise. :param value: The value to clamp :type value: number @@ -840,7 +840,7 @@ Math Extensions .. lua:method:: clamp01(value) - Clamp value between 0 and 1 + Clamp the value between 0 and 1. :param value: The value to clamp :type value: number diff --git a/docs/source/api/physics2d.rst b/docs/source/api/physics2d.rst index 4770451..f408371 100644 --- a/docs/source/api/physics2d.rst +++ b/docs/source/api/physics2d.rst @@ -473,7 +473,7 @@ Collision .. lua:method:: collide(otherCollider) - Checks the collision between two colliers: this one and another collider and gives infomation about it + Checks the collision between this collider and another collider, and returns information about the collision. :param otherCollider: The other collider to collide with :type otherCollider: collider @@ -481,11 +481,11 @@ Collision :return: ``didCollide[, point, normal, penetration]`` - `didCollide` is whether the collision happened :rtype: boolean[, vec2, vec2, number] - .. helptext:: allows users to do check collision between two colliders + .. helptext:: check for a collision with another collider .. lua:method:: overlap(otherCollider) - Checks overlapping between two colliers: this one and another collider + Checks if the collider overlaps with another collider. :param otherCollider: The other collider to overlap with :type otherCollider: collider @@ -493,7 +493,7 @@ Collision :return: Checks whether the two colliders are overlapping :rtype: boolean - .. helptext:: allows users to do check if two colliders are overlapping + .. helptext:: check for an overlap with another collider .. lua:class:: circle: collider @@ -909,11 +909,11 @@ Settings .. lua:attribute:: debugDraw: boolean - Draws physics objects in the scene + Draws physics objects in the scene. .. lua:attribute:: gravity: vec2 - Changes the gravity of the physics world + Changes the gravity of the physics world. .. lua:attribute:: velocityIterations: number From a098e06629ebbb387a0894ddd6880a81b4ded15b Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 21:21:25 -0400 Subject: [PATCH 19/21] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François Pérusse --- docs/source/api/physics2d.rst | 2 +- docs/source/api/physics3d.rst | 8 ++++---- docs/source/api/scene.rst | 2 +- docs/source/api/sound.rst | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/api/physics2d.rst b/docs/source/api/physics2d.rst index f408371..8827ced 100644 --- a/docs/source/api/physics2d.rst +++ b/docs/source/api/physics2d.rst @@ -921,4 +921,4 @@ Settings .. lua:attribute:: paused: boolean - Whether you want to paused the physics in a scene \ No newline at end of file + Get or set whether the physics simulation is currently paused. \ No newline at end of file diff --git a/docs/source/api/physics3d.rst b/docs/source/api/physics3d.rst index adac378..14b0481 100644 --- a/docs/source/api/physics3d.rst +++ b/docs/source/api/physics3d.rst @@ -505,7 +505,7 @@ physics3d .. lua:attribute:: body: physics3d.body - The body of the collider that was hit by the ray + The body of the collider which was hit by the ray. .. helptext:: get the raycast hit body @@ -516,18 +516,18 @@ Settings .. lua:attribute:: debugDraw: boolean - Draws physics objects in the scene + Draws physics objects in the scene. .. helptext:: draws physics objects in the scene .. lua:attribute:: gravity: vec3 - Changes the gravity of the physics world + Changes the gravity of the physics world. .. helptext:: gravity of the physics world .. lua:attribute:: paused: boolean - Whether you want to paused the physics in a scene + Get or set whether the physics simulation is paused. .. helptext:: pauses the physics world \ No newline at end of file diff --git a/docs/source/api/scene.rst b/docs/source/api/scene.rst index fcb08e6..28e146b 100644 --- a/docs/source/api/scene.rst +++ b/docs/source/api/scene.rst @@ -186,7 +186,7 @@ scene .. lua:method:: forEach(loopFunction, [includeFlag = scene.DEFAULT]) - Inputs a callback to that is called while looping over entities in the scene + Call a function `loopFunction` for each matching entity in the scene. :param loopFunction: Function to loop over :type loopFunction: function(entity) diff --git a/docs/source/api/sound.rst b/docs/source/api/sound.rst index 5706987..a7508f6 100644 --- a/docs/source/api/sound.rst +++ b/docs/source/api/sound.rst @@ -179,7 +179,7 @@ The sound module provides a way to play and manage sound effects and background .. lua:attribute:: samplerate: number - Get the samplerate of the sound instance + Get the sample rate of the sound instance. .. helptext:: current playback samplerate From d02e6c132c14d98894e32deb8e7b1b68b63dd170 Mon Sep 17 00:00:00 2001 From: Lioncub901 <88890833+Lioncub901@users.noreply.github.com> Date: Sun, 29 Mar 2026 21:23:36 -0400 Subject: [PATCH 20/21] Update animation.rst --- docs/source/api/animation.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 72fad42..3a31a1d 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -84,10 +84,6 @@ Animation Starts to play the animation - .. lua:method:: pause() - - Pauses the animation - .. lua:method:: pause() Pauses the animation From f6eceae2b864259966f32dff5e057d03007dd3b3 Mon Sep 17 00:00:00 2001 From: Israel Uche Date: Thu, 9 Apr 2026 19:29:01 -0400 Subject: [PATCH 21/21] Fixed the help text and many errors. Also added the pixel writing and reading funcitons --- docs/source/api/animation.rst | 176 +++++++++++++++++++++++++-------- docs/source/api/graphics.rst | 2 + docs/source/api/image.rst | 95 ++++++++++++++++++ docs/source/api/input.rst | 56 +++++------ docs/source/api/math_types.rst | 42 +++++++- docs/source/api/physics2d.rst | 12 ++- docs/source/api/sound.rst | 4 +- docs/source/api/style.rst | 2 + docs/source/api/tilemap.rst | 176 ++++++++++++++++++++++++++------- docs/source/api/time.rst | 28 +++++- 10 files changed, 478 insertions(+), 115 deletions(-) diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst index 3a31a1d..93da8df 100644 --- a/docs/source/api/animation.rst +++ b/docs/source/api/animation.rst @@ -3,7 +3,8 @@ animation API for creating animation -**It Contains** +Content +####### - ``animation`` - information on a animation - ``animation.track`` - information on how animation tracks work @@ -39,16 +40,24 @@ Animation :return: A new animation :rtype: animation + + .. helptext:: the constructor of the animation class .. lua:attribute:: id: number - Get or set the animation's identifier + Sets/gets the animation's identifier + + .. helptext:: the animation's identifier .. lua:attribute:: name: string + .. helptext:: the animation's name + .. lua:method:: property(propertyName) - Adds a new track to the animation using that property. Type of the track is inferred. + Adds a new track to the animation using that property. + + .. note:: the type of the track is inferred based on the type of the property :param propertyName: The string that directs to the proper target (property name) :type propertyName: string @@ -62,10 +71,14 @@ Animation * ``"sound"`` - creates a sound track * ``"clip"`` - creates an animation clip track + .. helptext:: adds a new track to the animation + .. lua:method:: [index] (propertyName) Adds a new track by passing the property name as index. + .. helptext:: adds a new track to the animation + .. lua:method:: removeTrack(trackObj) Removes this track @@ -73,6 +86,8 @@ Animation :param trackObj: the track to be removed :type trackObj: animation.track + .. helptext:: removes track + .. lua:method:: update(timeDelta) Updates the animation by ``time.delta`` @@ -80,52 +95,70 @@ Animation :param timeDelta: time.delta :type timeDelta: number + .. helptext:: updates the animation + .. lua:method:: play() Starts to play the animation + .. helptext:: plays the animation + .. lua:method:: pause() Pauses the animation + .. helptext:: pauses the animation + .. lua:method:: restart([shouldPlay = true]) - Restarts the animation from the beginning + Restarts the animation :param shouldPlay: Whether the animation should start playing :type shouldPlay: boolean + .. helptext:: restarts the animation + .. lua:attribute:: playing: boolean Checks if the animation is playing + .. helptext:: checks if the animation is playing + .. lua:attribute:: tracks: table - Allow one to get the tracks of the animation + Gets the tracks of the animation + + .. helptext:: checks if the animation is playing .. lua:attribute:: duration: number - Gets the duration of an animation + Gets the duration of the animation + + .. helptext:: gets the duration of the animation .. lua:attribute:: time: number Gets/Sets the time elapsed through the animation + .. helptext:: the elapsed time through the animation + .. lua:attribute:: loopAmount: integer Sets the amount of times the animation loops. Set to 0 for an infinite loop. + .. helptext:: the amount of times the animation loops + .. lua:attribute:: onComplete: function - Set a function to call when the animation is complete. + Sets a function to call when the animation has been completed. + + .. helptext:: sets a function to call when the animation has been completed. .. lua:method:: group(animation1, ... , animationX) - Groups multiple animations into one animations so they can be played synchronously using the same time. - Each animation gets their own track (``type: animationClip``). - At the front of the track (0 second), an animation clip key frame is placed with each animation as an animation clip. + Groups multiple animations into one animations so they can be played synchronously using the same time. Each animation gets their own track (``type: animationClip``). At the front of the track (0 second), an animation clip key frame is placed with each animation as an animation clip. - `Note that the duration of the grouped animation is the length of the longest animation.` + .. note:: Note that the duration of the grouped animation is the length of the longest animation. :param animation1: A single animation to be added to the group :type animation1: animation @@ -133,12 +166,14 @@ Animation :return: A new animation able to play all the animations synchronously :rtype: animation + .. helptext:: groups multiple animations to play synchronously + .. lua:method:: sequence(animation1, ... , animationX) Groups multiple animations into a single animation so they can be played sequentially. Each animation is placed in a singlar track one after another (``type: animationClip``). - `Note that the duration of the sequenced animation is the sum of all the animations' duration.` + .. note:: Note that the duration of the sequenced animation is the sum of all the animations' duration. :param animation1: A single animation to be added to the sequence :type animation1: animation @@ -146,6 +181,8 @@ Animation :return: A new animation able to play all the animations sequentially :rtype: animation + .. helptext:: groups multiple animations to play in sequence + Animation Track ############### @@ -154,14 +191,14 @@ Animation Track .. code-block:: lua :caption: How to create an animation.track - local ball = { x = 0, y = 3, col = color.red, image = asset.ball1 } - + ball = { x = 500, y = 400, col = color.red, image = asset.builtin.Planet_Cute.Character_Boy } + ballColorAnimation = animation(ball) - + -- Animate the ball's color colorTrack = ballColorAnimation.col - -- Set the key frames of the ball + -- Sets the key frames of the ball colorTrack :key(0.0) -- because the value was not inputted the first key's value is set to color.red because that is the current value of "col" :key(1.0, color.blue, tween.hold) @@ -172,23 +209,23 @@ Animation Track firstKey.value = color.white colorTrack:keyAtTime(1.0).value = color.black -- change the key value at time 1.0 from blue to magenta colorTrack[2.0].value = color.magenta -- another way to get time - + ballSpriteAnimation = animation(ball) - + -- animate ball sprite with frames - spriteTrack = ballAnimation:property("image") -- another way to create a track for the "image" property - spriteTrack:frames({asset.ball1, asset.ball2, asset.ball3}, { loop = 4, fps = 6 }) -- add frames to the track and make it loop 4 times at 6 fps - - groupAnimation = animation.bundle(ballColorAnimation, ballSpriteAnimation) + spriteTrack = ballSpriteAnimation:property("image") -- another way to create a track for the "image" property + spriteTrack:frames({asset.builtin.Planet_Cute.Character_Boy, asset.builtin.Planet_Cute.Character_Cat_Girl, asset.builtin.Planet_Cute.Character_Horn_Girl}, { loop = 4, fps = 6 }) -- add frames to the track and make it loop 4 times at 6 fps + + groupAnimation = animation.group(ballColorAnimation, ballSpriteAnimation) spriteAnimationTrack = groupAnimation.tracks[2] -- get the second track secondTrackKey = spriteAnimationTrack:keyAtIndex(1) local theDuration = secondTrackKey.duration -- get first key frame secondTrackKey.duration = theDuration * 2 -- make the sprite animation loop 2 times - + groupAnimation:play() -- every frame - groupAnimation:update() + groupAnimation:update(time.delta) .. lua:attribute:: type: trackType @@ -206,28 +243,43 @@ Animation Track * ``animation.track.function`` - function call track * ``animation.track.animationClip`` - animationClip track: plays another animation + .. helptext:: returns this track's type. + .. lua:attribute:: target: table/userdata The table/userdata that contains that animated property + .. helptext:: the table/userdata that contains that animated property + .. lua:attribute:: property: string The string that directs to the proper target (property name) + .. helptext:: the string that directs to the proper target + .. lua:attribute:: duration: number - The duration of the track which is the last key frame's time, in seconds, plus its duration + The duration of the track + + .. helptext:: the duration of the track .. lua:attribute:: fps: integer The frames that are placed pre second + .. helptext:: the frames that are placed pre second + .. lua:attribute:: timeDelta: number - Gap of time between each frame played. + The gap of time between each frame placed. + + .. helptext:: the gap of time between each frame placed. .. lua:method:: frames(theFrames[, frameProperties]) + .. helptext:: quickly sets the frames of the track + .. lua:method:: frames() + A way to quickly get/set the keyframes for a sprite track (``type = animation.track.sprite``). It uses the timeDelta as a way to space out the sprites. :param theFrames: a table of frames to represent the frames of the sprite animation @@ -240,30 +292,38 @@ Animation Track * ``"fps"`` - another way of doing delta but sets the fps of the sprites * ``"loop"`` - number of times the sprites should loop + .. helptext:: quickly gets the frames of the track + .. lua:method:: adjustFrames() - Adjust the frames to fit the new timeDelta/fps. + Adjusts the frames to fit the new timeDelta/fps. + + .. helptext:: adjusts the frames to fit the new timeDelta/fps .. lua:attribute:: count: integer The number of key frames in a track. + .. helptext:: the number of key frames in a track + .. lua:method:: key(time[, value, properties]) Add a key frame to the track. (supports chaining) :param time: The time of the key frame :type time: number - :param value: The value of the key frame. If ``trackType = animation.track.vec2`` then value should be a ``vec2``. Every type follows this rule. If there is no value then set to current value of ``target[property]`` + :param value: The value of the key frame. Should be the same type as the track type. :type value: any type :param properties: Quick way to add properties of key :type properties: table or easing enum + .. note:: if value is nil then it will be set to current value of ``target[property]`` + **Possible properties** `If easing enum` - Set the easing. Examples: ``tween.cubicIn`` or ``tween.hold`` + Sets the easing. Examples: ``tween.cubicIn`` or ``tween.hold`` `If table:` @@ -276,6 +336,7 @@ Animation Track * ``"duration"`` - Sets the duration of the key frame (``type: number``) * ``"start"`` - Sets the start time of the key frame (``type: number``) + .. helptext:: adds a key to the track .. lua:method:: keyAtIndex(keyIndex) @@ -287,6 +348,8 @@ Animation Track :return: Key at that index :rtype: animation.key + .. helptext:: returns the key frame at this index + .. lua:method:: keyAtTime(time) Returns the key frame at this time @@ -297,13 +360,17 @@ Animation Track :return: Key at that time :rtype: animation.key + .. helptext:: returns the key frame at this time + .. lua:method:: [index] (time) Does the same thing as ``keyAtTime`` + .. helptext:: returns the key frame at this time + .. lua:method:: custom ([function]) - This allows this track to use a custom function instead of a property to set the target + Allows track to use a custom function to set the target :param function: Sets the custom function if no input then use default behavior :type function: function @@ -320,15 +387,22 @@ Animation Track boy.rotation = quat.eulerAngles(0, 0, value) end) + .. helptext:: allows track to use a custom function to set the target + .. lua:attribute:: openBeginning: boolean This is a variable that sets the 0 second key frame to be open. When true, the track will add a key frame at 0 second time and set the value to the current property value. - This can be used to smoothly go from gameplay to a cut scene without an abrupt cut. + + .. note:: This can be used to smoothly go from gameplay to a cut scene without an abrupt cut. + + .. helptext:: makes the beginning of the animation open .. lua:attribute:: openEasing: animation.easing This is the easing of the open key frame + .. helptext:: this is the easing of the open key frame + Animation Key ############# @@ -336,42 +410,54 @@ Animation Key .. lua:attribute:: time: number - Changes the time of the keyframe + The time of the keyframe - `Note: This method might change the key frames index in the list` + .. note:: this method might change the key frames index in the list + + .. helptext:: the time of the keyframe .. lua:attribute:: value: number - Changes the value of the keyframe + The value of the keyframe + + .. helptext:: the value of the keyframe .. lua:attribute:: duration: number - Changes the duration of the keyframe for sound and animation clip key frames + The duration of the keyframe for sound and animation clip key frames + + .. helptext:: the duration of the keyframe .. lua:attribute:: startTime: number - Changes the start time (offset) of sound and animation clip + The start time (offset) of sound and animation clip + + .. helptext:: the start time of the keyframe .. lua:attribute:: originalDuration: number Gets the original duration of sound or animation clip - .. lua:method:: restoreDuration() - - Resets the duration of this key frame (sound or animation clip) to its original duration + .. helptext:: gets the original duration of sound or animation clip .. lua:method:: delete() Deletes this key frame from its parent track list + + .. helptext:: deletes this key frame from its parent track list .. lua:attribute:: valid: boolean Checks if the keyframe is still valid + .. helptext:: checks if the keyframe is still valid + .. lua:attribute:: easing: animation.easing Gets the easing of this key + .. helptext:: gets the easing of this key + Animation Easing ################ @@ -379,13 +465,19 @@ Animation Easing .. lua:attribute:: type: tween easing enum - Changes the type of easing of the key frame + The type of easing of the key frame + + .. helptext:: gets the easing of this key .. lua:attribute:: strength: number - Changes the strength of the easing + Sets/gets the strength of the easing + + .. helptext:: the strength of the easing .. lua:attribute:: loopAmount: integer - Changes the amount of previous frames to loop + Sets/gets the amount of previous frames to loop + + .. helptext:: the amount of previous frames to loop diff --git a/docs/source/api/graphics.rst b/docs/source/api/graphics.rst index 69362a9..e503f31 100644 --- a/docs/source/api/graphics.rst +++ b/docs/source/api/graphics.rst @@ -291,6 +291,8 @@ Text .. lua:function:: textGlyphBounds(str, pos[, size]) + .. helptext:: gets the bound of the glyph + (Experimental subject to change) Gets the bound each characters in a text :param str: The text to query diff --git a/docs/source/api/image.rst b/docs/source/api/image.rst index 38a7c52..91f59f6 100644 --- a/docs/source/api/image.rst +++ b/docs/source/api/image.rst @@ -183,6 +183,101 @@ Image .. helptext:: generate irradiance data into a target image + .. lua:method:: setPixel(xPos, yPos, pixelColor) + + Sets an inputed position to a new color + + :param xPos: The x position of the image + :type xPos: integer + :param yPos: The y position of the image + :type yPos: integer + :param pixelColor: The color to change the pixel to + :type pixelColor: color + + .. helptext:: sets an inputed position to a new color + + .. lua:method:: setValue(xPos, yPos, r, g, b, a) + + Same as set pixel but the inputted color value are from 0 to 1 + + :param xPos: The x position of the image + :type xPos: integer + :param yPos: The y position of the image + :type yPos: integer + + .. helptext:: sets an inputed position to a new color using value from 0 to 1 + + .. lua:method:: setForEach(loopingFunction) + + Loop over each pixel of the image and set its color value (0 to 1) + + :param loopingFunction: The function to loop over + :type loopingFunction: function + + .. code-block:: lua + :caption: How to set the pixels of an image + + img = image(255, 255) + + img:setForEach(function(x, y) + return math.random(), math.random(), math.random(), 1 + end) + + img:apply() + + .. helptext:: loops over every pixel of the image and output a color value + + .. lua:method:: apply() + + Applys all the colors that were set + + .. helptext:: applys all the colors that were set + + .. lua:method:: readback([immediately = true, includeMips = false]) + + Allows the user to get the image's color data + + :param immediately: Whether the image should allow reading immediately + :type immediately: boolean + :param includeMips: Whether the mip maps should be included + :type includeMips: boolean + + .. code-block:: lua + :caption: How to read the pixel values of an image + + -- img is a image + + img:readback() -- allows reading the pixels of the image + local pixelColor = color(img:getPixel(200, 200)) + + .. helptext:: allows the user to get the image's color data + + .. lua:method:: getPixel(xPos, yPos) + + Gets the color at the inputted position (0 to 255) + + :param xPos: The x position of the image + :type xPos: integer + :param yPos: The y position of the image + :type yPos: integer + :return: The colors at the inputted position (r, g, b, a) (0 to 255) + :rtype: number, number, number, number + + .. helptext:: gets the color at the inputted position + + .. lua:method:: getValue(xPos, yPos) + + Gets the color values at the inputted position (0 to 1) + + :param xPos: The x position of the image + :type xPos: integer + :param yPos: The y position of the image + :type yPos: integer + :return: The color values at the inputted position (r, g, b, a) (0 to 1) + :rtype: number, number, number, number + + .. helptext:: gets the color values at the inputted position + Image Formats ------------- diff --git a/docs/source/api/input.rst b/docs/source/api/input.rst index fe68ef1..0eec9ed 100644 --- a/docs/source/api/input.rst +++ b/docs/source/api/input.rst @@ -1051,42 +1051,42 @@ Mouse **Global Mouse Funcitons** -.. lua:method:: mousePressed(mouseName) +.. lua:function:: mousePressed(mouseName) - Function for when the mouse is pressed + Function for when the mouse is pressed - :param mouseName: return the name of the mouse being selected ("left", "right", "middle") - :type mouseName: string - - .. helptext:: function that is called when the mouse has been pressed + :param mouseName: return the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + + .. helptext:: function that is called when the mouse has been pressed -.. lua:method:: mouseReleased(mouseName) +.. lua:function:: mouseReleased(mouseName) - Function for when the mouse is released + Function for when the mouse is released - :param mouseName: return the name of the mouse being selected ("left", "right", "middle") - :type mouseName: string - - .. helptext:: function that is called when the mouse has been released + :param mouseName: return the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + + .. helptext:: function that is called when the mouse has been released -.. lua:method:: mouseChanged(mouseName, changeState) +.. lua:function:: mouseChanged(mouseName, changeState) - Function for when the mouse has been changed + Function for when the mouse has been changed - :param mouseName: Returns the name of the mouse being selected ("left", "right", "middle") - :type mouseName: string - :param changeState: Inputs true if the mouse was pressed or false if the mouse was released - :type wasPressed: boolean - - .. helptext:: function that is called when the mouse has been changed + :param mouseName: Returns the name of the mouse being selected ("left", "right", "middle") + :type mouseName: string + :param changeState: Inputs true if the mouse was pressed or false if the mouse was released + :type wasPressed: boolean + + .. helptext:: function that is called when the mouse has been changed -.. lua:method:: mouseMoved(deltaX, deltaY) +.. lua:function:: mouseMoved(deltaX, deltaY) - Function for when the mouse has been moved + Function for when the mouse has been moved - :param deltaX: The delta x of the mouse - :type deltaX: number - :param deltaY: The delta y of the mouse - :type deltaY: number - - .. helptext:: function that is called when the mouse has been moved + :param deltaX: The delta x of the mouse + :type deltaX: number + :param deltaY: The delta y of the mouse + :type deltaY: number + + .. helptext:: function that is called when the mouse has been moved diff --git a/docs/source/api/math_types.rst b/docs/source/api/math_types.rst index 094dfcb..3e3d791 100644 --- a/docs/source/api/math_types.rst +++ b/docs/source/api/math_types.rst @@ -717,19 +717,29 @@ Axis-Aligned Bounding Box (AABB) .. lua:attribute:: min: vec3 + .. helptext:: minimum position of the bound + .. lua:attribute:: max: vec3 + .. helptext:: maximum position of the bound + .. lua:attribute:: size: vec3 Size of the bounding box + .. helptext:: size of the bound + .. lua:attribute:: offect: vec3 Offset of the bounding box + .. helptext:: offset of the bound + .. lua:attribute:: valid: boolean Checks if the bounding box is valid + + .. helptext:: checks if the bound is valid .. lua:method:: set(min, max) @@ -738,11 +748,15 @@ Axis-Aligned Bounding Box (AABB) :param max: The maximum position of the bounding box :type max: vec3 + .. helptext:: sets the new min and max of the bound + .. lua:method:: translate(amount) :param amount: The amount to move the bounding box :type amount: vec3 + .. helptext:: translates the bounding box + .. lua:method:: transform(transformMatrix) :param transformMatrix: The matrix used to transform the current matrix @@ -750,6 +764,8 @@ Axis-Aligned Bounding Box (AABB) :return: New bounds to fit the transformed bound :rtype: aabb + .. helptext:: creates news bound to fix the transformed bound + .. lua:method:: encapsulate(point) Adjust the bound to fit a point @@ -757,6 +773,8 @@ Axis-Aligned Bounding Box (AABB) :param point: The point you want to fit :type point: vec3 + .. helptext:: adjust the bound to fit a point + .. lua:method:: encapsulate(otherAABB) Adjust the bound to fit another bound @@ -764,6 +782,8 @@ Axis-Aligned Bounding Box (AABB) :param otherAABB: The aabb you want to fit :type otherAABB: aabb + .. helptext:: adjust the bound to fit another bound + .. lua:method:: raycast(origin, dir) :param origin: The position of the ray @@ -772,6 +792,8 @@ Axis-Aligned Bounding Box (AABB) :type dir: mat4 :return: The hit infomation of the raycast :rtype: hit + + .. helptext:: performs a raycast on the bound box .. lua:class:: hit @@ -779,10 +801,14 @@ Axis-Aligned Bounding Box (AABB) The position where the raycast hit + .. helptext:: the position where the raycast hit + .. lua:attribute:: normal: vec3 The normal of the point hit + .. helptext:: the normal of the point hit + Math Extensions ############### @@ -794,6 +820,8 @@ Math Extensions .. lua:method:: lerp(a, b, t) + Interpolate a and b by the a given factor (typically between 0 and 1) + :param a: The first point :type a: number :param b: The second point @@ -803,9 +831,11 @@ Math Extensions :return: The interpolated value between a and b at ratio t. :rtype: number + .. helptext:: interpolate two numbers by a t value + .. lua:method:: inverseLerp(a, b, v) - Give the t (progress) value that v is in a and b + Returns the ratio from a to b where the interpolated value is v. :param a: The first point :type a: number @@ -816,6 +846,8 @@ Math Extensions :return: The ratio from a to b at which the interpolated value is v :rtype: number + .. helptext:: the ratio from two number where the interpolated value is v + .. lua:method:: sign(value) Returns -1 if value < 0, 0 if value == 0, 1 if value > 0. @@ -825,6 +857,8 @@ Math Extensions :return: The sign of the value :rtype: number + .. helptext:: returns -1 if value < 0, 0 if value == 0, 1 if value > 0 + .. lua:method:: clamp(value, a, b) Clamp the value between `a` and `b`. If the value is less than `a`, the function outputs `a`. If the value is greater than `b`, the function outputs `b`. Returns value otherwise. @@ -838,6 +872,8 @@ Math Extensions :return: The t (progress) that v is between a and b :rtype: number + .. helptext:: clamp the value between a and b + .. lua:method:: clamp01(value) Clamp the value between 0 and 1. @@ -845,4 +881,6 @@ Math Extensions :param value: The value to clamp :type value: number :return: The clamped value - :rtype: number \ No newline at end of file + :rtype: number + + .. helptext:: clamp the value between 0 and 1 \ No newline at end of file diff --git a/docs/source/api/physics2d.rst b/docs/source/api/physics2d.rst index 8827ced..a78732d 100644 --- a/docs/source/api/physics2d.rst +++ b/docs/source/api/physics2d.rst @@ -911,14 +911,24 @@ Settings Draws physics objects in the scene. + .. helptext:: draws physics objects in the scene + .. lua:attribute:: gravity: vec2 Changes the gravity of the physics world. + .. helptext:: gravity of the physics world + .. lua:attribute:: velocityIterations: number + .. helptext:: velocity iterations + .. lua:attribute:: positionIterations: number + .. helptext:: position iterations + .. lua:attribute:: paused: boolean - Get or set whether the physics simulation is currently paused. \ No newline at end of file + Get or set whether the physics simulation is currently paused. + + .. helptext:: pauses the physics simluation \ No newline at end of file diff --git a/docs/source/api/sound.rst b/docs/source/api/sound.rst index a7508f6..b96749a 100644 --- a/docs/source/api/sound.rst +++ b/docs/source/api/sound.rst @@ -134,10 +134,12 @@ The sound module provides a way to play and manage sound effects and background .. lua:attribute:: length: number [readonly] Gets the length of this sound source (in seconds) + + .. helptext:: gets the length of this sound source (in seconds) .. lua:attribute:: key: assetKey - The asset key for this sound (if it has one) + The asset key for this sound (if it has one) .. helptext:: length of the sound in seconds diff --git a/docs/source/api/style.rst b/docs/source/api/style.rst index 34f17a1..6917a82 100644 --- a/docs/source/api/style.rst +++ b/docs/source/api/style.rst @@ -605,6 +605,8 @@ Text Style Adds a custom font in Codea using it's asset key + .. helptext:: adds a custom font in Codea using it's asset key + .. lua:function:: fontSize(size) .. helptext:: set the font size for text() diff --git a/docs/source/api/tilemap.rst b/docs/source/api/tilemap.rst index 5f28eef..f706259 100644 --- a/docs/source/api/tilemap.rst +++ b/docs/source/api/tilemap.rst @@ -1,11 +1,13 @@ tilemap ======= -Api for creating tile maps +API for creating tile maps -**It Contains** - - ``tm.tiles`` - infomation on a single tile - - ``tm.ruleset`` - infomation on how sprites should behavior in a tile +Content +####### + + - ``tm.tiles`` - information on a single tile + - ``tm.ruleset`` - information on how sprites should behavior in a tile - ``tm.tileset`` - collection of tiles used in the scene - ``tm.layer`` - the placement of tiles in the single layer - ``tm.tilemap`` - the grouping of tilemap layers to draw to the scene @@ -32,9 +34,14 @@ Tile .. lua:attribute:: id: number - .. lua:method:: sprite([spriteIcon]) + .. helptext:: the tile's identifier + + .. lua:method:: sprite(spriteIcon) + + .. helptext:: sets the sprite of the rule + .. lua:method:: sprite() - Set/Get the sprite image of the tile + Sets/gets the sprite image of the tile :param spriteIcon: The image that the tile contains :type spriteIcon: sprite @@ -44,9 +51,11 @@ Tile :return: The sprite image :rtype: sprite + .. helptext:: gets the sprite of the tile + .. lua:method:: group(groupNum) - Set the sprite image of the tile + Sets the group of the tile :param groupNum: The group number the tile is from :type groupNum: number @@ -54,25 +63,32 @@ Tile :return: self for function chaining :rtype: tile + .. helptext:: sets the group of the tile + .. lua:method:: collision(mode) - Set the collision mode of the tile + Sets the collision mode of the tile :param mode: The enum of the collision :type mode: enum :return: self for function chaining :rtype: tile - + **Collision Mode Enum:** * ``tm.collision.none`` - no collision * ``tm.collision.square`` - for square collision * ``tm.collision.sprite`` - for sprite collision - .. lua:method:: ruleset([theRuleset]) + .. helptext:: sets the collision mode of the tile + + .. lua:method:: ruleset(theRuleset) - Set/Get the ruleset of the tile + .. helptext:: sets the ruleset of the tile + .. lua:method:: ruleset() + + Sets/gets the ruleset of the tile :param theRuleset: The ruleset to be applied to the tile :type theRuleset: tm.ruleset @@ -82,21 +98,24 @@ Tile :return: The ruleset of the tile :rtype: tm.ruleset + .. helptext:: gets the ruleset of the tile + Ruleset ####### .. lua:class:: ruleset - A ruleset is a object to allows the user to determine how the same tiles should a aranged using certain rules. - Having a ruleset simplify the creation of tilemap as common patterns can be set as a rule + A ruleset is an object to determine how the same tiles should arrange using certain rules. .. lua:method:: rule() - Creates a rule in the ruleset and select it. Following ruleset functions will apply to this rule. + Creates a rule in the ruleset and selects it. Following ruleset functions will apply to this rule. :return: self for function chaining. :rtype: ruleset + .. helptext:: creates a rule in the ruleset + .. lua:method:: [index] (ruleNum) Select the rule in the ruleset. Following ruleset functions will apply to this rule. @@ -107,11 +126,17 @@ Ruleset :return: self for function chaining :rtype: ruleset + .. helptext:: creates a rule in the ruleset + **Below happens to rule created above** - .. lua:method:: sprite([spriteIcon]) + .. lua:method:: sprite(spriteIcon) + + .. helptext:: sets the sprite image of the rule - Set/Get the sprite image of the rule + .. lua:method:: sprite() + + Sets/gets the sprite image of the rule :param spriteIcon: The image that the rule contains :type spriteIcon: sprite @@ -121,9 +146,11 @@ Ruleset :return: One sprite image for regular and a table for `random` :rtype: sprite or table - .. lua:method:: random([spriteList]) + .. helptext:: gets the sprite image of the rule + + .. lua:method:: random(spriteList) - Set the sprite that will be randomly selected (good for dirt tiles) + Sets the sprites that will be randomly selected :param spriteList: The images that the rule contains :type spriteList: table @@ -131,9 +158,13 @@ Ruleset :return: self for function chaining :rtype: ruleset + .. helptext:: sets the sprites that will be randomly selected + .. lua:method:: area(row1,... , rowX) - Set the tile area rule to determine with sprite should be displayed in the correct spot. The rows must be a old number 3 - 7. Rows and cols should be the same length + Sets the tile area rule to determine which sprite should be displayed in the correct spot. + + .. note:: The rows must be an odd number from 3 to 7. Rows and columns should be the same length :param rowX: The layout of the tile (sprite) with other tiles :type spriteList: string @@ -158,7 +189,13 @@ Ruleset :return: self for function chaining :rtype: ruleset - .. lua:method:: rotate([shouldRotate]) + .. helptext:: sets the tile area rule to determine which sprite should be displayed + + .. lua:method:: rotate(shouldRotate) + + .. helptext:: sets the rotation of the rule's tile + + .. lua:method:: rotate() Rotates the rule's tile @@ -168,7 +205,13 @@ Ruleset :return: self for function chaining :rtype: ruleset - .. lua:method:: flip([flipX, flipY]) + .. helptext:: gets the rotation of the rule's tile + + .. lua:method:: flip(flipX, flipY) + + .. helptext:: sets the flip of the rule + + .. lua:method:: flip() Flips the rule's tile @@ -180,9 +223,11 @@ Ruleset :return: self for function chaining :rtype: ruleset + .. helptext:: gets the flip of the rule + .. lua:method:: collision(mode) - Set the collision mode of the rule's tile + Sets the collision mode of the rule's tile :param mode: The enum of the collision :type mode: enum @@ -190,6 +235,8 @@ Ruleset :return: self for function chaining :rtype: tile + .. helptext:: sets the collision mode of the rule's tile + .. lua:method:: delete() Deletes the currently selected rule from the ruleset @@ -197,6 +244,8 @@ Ruleset :return: self for function chaining :rtype: tile + .. helptext:: deletes the currently selected rule from the ruleset + .. lua:method:: clear() Clears all rules from the ruleset @@ -204,10 +253,13 @@ Ruleset :return: self for function chaining :rtype: tile + .. helptext:: clears the ruleset + .. lua:attribute:: count: number Gets the number of rules in ruleset + .. helptext:: the amount of rules Tileset ####### @@ -233,9 +285,11 @@ Tileset :return: The newly created tile :rtype: tile + .. helptext:: create a tile in the tileset + .. lua:method:: [index] (tileId) - Select tile from tileset using its id + Selects a tile from tileset using its id :param tileId: The id of the tile. :type tileId: integer @@ -243,6 +297,8 @@ Tileset :return: Selected tile :rtype: tile + .. helptext:: selects a tile from tileset using its id + .. lua:method:: [index] (tileName) Select tile from tileset using its name @@ -253,6 +309,8 @@ Tileset :return: Selected tile :rtype: tile + .. helptext:: selects a tile from tileset using its name + .. lua:method:: clear() Clears all tiles from the tileset @@ -260,10 +318,14 @@ Tileset :return: self for function chaining :rtype: tile + .. helptext:: clears the tileset + .. lua:attribute:: count: number Gets the number of rules in ruleset + .. helptext:: the amount of tiles in the tileset + Tilemap ####### @@ -278,7 +340,7 @@ Tilemap .. lua:method:: layer(layerName) - Creates layer in the tilemap + Creates a layer in the tilemap :param layerName: Name of the layer in this tilemap :type layerName: string @@ -286,9 +348,11 @@ Tilemap :return: The newly created layer :rtype: layer + .. helptext:: creates a layer in the tilemap + .. lua:method:: [index] (layerName) - Select layer from tilemap using its name + Gets a layer from tilemap using its name :param layerName: The name of the layer :type layerName: string @@ -296,18 +360,26 @@ Tilemap :return: Selected layer :rtype: layer + .. helptext:: gets a layer from tilemap using its name + .. lua:method:: draw() - Draw all the layers of the tilemap + Draws all the layers of the tilemap + + .. helptext:: draws all the layers of the tilemap .. lua:attribute:: world2d: world2d Gets/sets the physics world. + .. helptext:: gets/sets the physics world. + .. lua:attribute:: tileset: tileset Gets/sets the tileset. + .. helptext:: Gets/sets the physics world. + Layer ##### @@ -324,11 +396,17 @@ Layer .. lua:attribute:: id: number - .. lua:attribute:: id: name + .. helptext:: the layer's identifier + + .. lua:attribute:: name: string + + .. helptext:: the layer's name .. lua:attribute:: offset: vec3 - Adjust the position of tilemap drawing + Adjusts the position of tilemap + + .. helptext:: adjusts the position of tilemap .. lua:method:: origin() @@ -337,20 +415,26 @@ Layer :return: The x, y, and z of the origin :rtype: number, number, number + .. helptext:: position of bottom left tile + .. lua:method:: size() - Size of the tilemap from min position to max position + Size of the tilemap :return: The x, y, and z of the size :rtype: number, number, number + .. helptext:: size of the tilemap + .. lua:method:: clear() Clears all tiles from the layer + .. helptext:: clears the layer + .. lua:method:: get(xPos, yPos) - Get the tileID at this position + Gets the tileID at this position :param xPos: The x position of the tile :type xPos: number (integer) @@ -360,11 +444,13 @@ Layer :return: The tileId at that position along with it's tileset :rtype: number, tileset - `If tile position does not exist then returns` ``tile.invalidID`` + .. note:: If tile position does not exist then returns 0 + + .. helptext:: gets the tile id at this position .. lua:method:: set(xPos, yPos, tileID|theTile) - set the tile at this position + Sets the tile at this position :param xPos: The x position of the tile :type xPos: number (integer) @@ -372,10 +458,14 @@ Layer :type yPos: number (integer) :param tileID|theTile: Can take in a tileID or the tile itself :type tileID|theTile: number | tile + + .. helptext:: gets the tile id at this position .. lua:method:: draw() - Draw this layer + Draws this layer + + .. helptext:: draws this layer .. lua:method:: fill(xPos, yPos, tileID|theTile) @@ -384,6 +474,8 @@ Layer :param tileID|theTile: Can take in a tileID or the tile itself :type tileID|theTile: number | tile + .. helptext:: fills the tilemap with this tile + .. lua:method:: resize(xSize, ySize) Resizes the layer to a new size @@ -393,16 +485,20 @@ Layer :param ySize: The new height of the layer :type ySize: number + .. helptext:: resizes the layer to the new size + .. lua:method:: visit(callback) - Goes through all the position of the the layers and calls this function. The callback function's input takes x, y, z, and tileID (the tile at that position) + Iterates through all the positions of the the layers and calls this function. The callback function's input takes x, y, z, and tileID (the tile at that position) :param callback: The function that will be call each position: function(x, y, z, tileID, tileset) :type callback: function(number, number, number, number, tileset) + .. helptext:: iterates over all the positions of the the layers + .. lua:method:: worldToTile(xPos, yPos) - Get the tile position from the world's position + Gets the tile position from the world's position :param xPos: The x position of the world :type xPos: number (integer) @@ -411,10 +507,12 @@ Layer :return: returns the tile position from world space :rtype: number, number + + .. helptext:: gets the tile position from the world's position .. lua:method:: tileToWorld(xPos, yPos) - Get the world position from the tiles's position + Gets the world position from the tiles's position :param xPos: The x position of the tile in layer :type xPos: number (integer) @@ -424,7 +522,11 @@ Layer :return: returns the world position from tile space :rtype: number, number + .. helptext:: gets the world position from the tiles's position + .. lua:method:: bounds() :return: returns bounds of the layer - :rtype: bounds.aabb \ No newline at end of file + :rtype: bounds.aabb + + .. helptext:: the bound of the layer \ No newline at end of file diff --git a/docs/source/api/time.rst b/docs/source/api/time.rst index c774732..4c0afcb 100644 --- a/docs/source/api/time.rst +++ b/docs/source/api/time.rst @@ -7,25 +7,37 @@ time The time between the last frame and this frame + .. helptext:: the time between the last frame and this frame + .. lua:attribute:: unscaledDelta: number Time delta without being affected by the time scale + .. helptext:: time delta without being affected by the time scale + .. lua:attribute:: fixedDelta: number - Set delta of the program (like setting the fps) + Sets the time delta of the program (like setting the fps) + + .. helptext:: sets the time delta of the program (like setting the fps) .. lua:attribute:: elapsed: number The time that has past since the program started + .. helptext:: the time that has past since the program started + .. lua:attribute:: unscaledElapsed: number The time that has past without being affected by the time scale + .. helptext:: the time that has past without being affected by the time scale + .. lua:attribute:: scale: number - Allowing the scaling of time to speed up or slow down (default is 1) + Sets/gets the scaling of time to speed up or slow down (default is 1) + + .. helptext:: the scaling of time Settings ######## @@ -38,12 +50,20 @@ For the scene time properties Set to false prevents the scene from updating, draw, touching automatically (for manual use) + .. helptext:: sets if the scene should auto update + .. lua:attribute:: maximumTimeStep: number + .. helptext:: the maximum Time Step + .. lua:attribute:: fixedDelta: number - Set delta of the scene (like setting the fps) + Sets the time delta of the scene (like setting the fps) + + .. helptext:: sets the time delta of the scene (like setting the fps) .. lua:attribute:: scale: number - Allowing the scaling of time to speed up or slow down (default is 1) \ No newline at end of file + Sets the scaling of time to speed up or slow down (default is 1) + + .. helptext:: sets the scaling of time to speed up or slow down \ No newline at end of file