diff --git a/docs/source/api/animation.rst b/docs/source/api/animation.rst new file mode 100644 index 0000000..20585aa --- /dev/null +++ b/docs/source/api/animation.rst @@ -0,0 +1,395 @@ +animation +========= + +Api for creating animation + +**It Contains** + + - ``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 +######### + +.. lua:class:: animation + + .. code-block:: lua + :caption: How to create a animation + + local ball = { x = 0, y = 3, col = color.red } + + 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 + + Can get and set an id for an animation + + .. lua:attribute:: name: string + + .. lua:method:: property(propertyName) + + 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) + :type propertyName: string + + :return: A new animation track + :rtype: animation.track + + **Unique Property Names** + + * ``"call"`` - creates a function track + * ``"sound"`` - creates a sound track + * ``"clip"`` - creates a animation clip track + + .. lua:method:: [index] (propertyName) + + Same as function above. You can just index using the property name to add new track + + .. lua:method:: removeTrack(trackObj) + + Removes this track from a list + + :param trackObj: the track to be removed + :type trackObj: animation.track + + .. lua:method:: update(timeDelta) + + Updates the animation based on ``time.delta`` + + :param timeDelta: time.delta + :type timeDelta: number + + .. lua:method:: play() + + Starts to play 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 the tracks of the animation + + .. lua:attribute:: duration: number + + Gets the duration of an animation + + .. lua:attribute:: time: number + + Gets/Sets the time elapsed through the animation + + .. lua:attribute:: loopAmount: integer + + Sets the amount of times the animation loop. Set to 0 for an infinite loop + + .. lua:attribute:: onComplete: function + + Set the function that is called when animation is completed + + .. lua:method:: group(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 grouped animation is the length of the longest animation` + + :param animation1: A single animation to be added to the group + :type animation1: animation + + :return: A new animation able to play all the animations synchronously + :rtype: 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``). + + `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 sequence + :type animation1: animation + + :return: A new animation able to play all the animations sequentially + :rtype: animation + +Animation Track +############### + +.. lua:class:: animation.track + + .. code-block:: lua + :caption: How to create a animation.track + + local ball = { x = 0, y = 3, col = color.red, image = asset.ball1 } + + ballColorAnimation = animation(ball) + + -- 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) + + -- 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 + secondTrackKey = spriteAnimationTrack:keyAtIndex(1) + local theDuration = secondTrackKey.duration -- get first keyframe + secondTrackKey.duration = theDuration * 2 -- make sprite animation loop 2 times + + groupAnimation:play() + + -- every frame + groupAnimation:update() + + .. lua:attribute:: type: trackType + + 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 + + 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 + + .. lua:attribute:: fps: integer + + The frames that are placed pre second + + .. lua:attribute:: timeDelta: number + + Gap of time between each frame placed. + + .. 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 + + :param theFrames: a table of frames to represent the frames of an 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) + * ``"fps"`` - another way of doing delta but sets the fps of the sprites + * ``"loop"`` - amount 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 + + .. lua:attribute:: count: integer + + The amount of keyframes in a track + + .. lua:method:: key(time[, value, properties]) + + 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. 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 + + **Possible properties** + + `If easing enum` + + Set the easing. Examples: ``tween.cubicIn`` or ``tween.hold`` + + `If table:` + + * ``"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``) + + `If table but type of track is sound or animation clip` + + * ``"duration"`` - Sets the duration of the key frame (``type: number``) + * ``"start"`` - Sets the start time of the key frame (``type: number``) + + + .. lua:method:: keyAtIndex(keyIndex) + + Returns the key frame at this index + + :param keyIndex: The index of the keyframe in the track keyframe list + :type keyIndex: integer + + :return: Key at that index + :rtype: animation.key + + .. lua:method:: keyAtTime(time) + + Returns the key frame at this time + + :param time: The time of the key frame + :type time: number + + :return: Key at that time + :rtype: animation.key + + .. lua:method:: [index] (time) + + 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 +############# + +.. lua:class:: animation.key + + .. lua:attribute:: time: number + + Changes the time of the keyframe + + `Note: This method might change the key frames index in the list` + + .. lua:attribute:: value: number + + Changes the value of the keyframe + + .. lua:attribute:: duration: number + + Changes the duration of the keyframe for sound and animation clip key frames + + .. lua:attribute:: startTime: number + + Changes the start time (offset) of sound and animation clip + + .. 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 it original duration + + .. lua:method:: delete() + + Deletes this key frame from its parent track list + + .. lua:attribute:: valid: boolean + + Checks if the keyframe is still valid + + .. lua:attribute:: easing: animation.easing + + Gets the easing of this key + +Animation Easing +################ + +.. lua:class:: animation.easing + + .. lua:attribute:: type: tween easing enum + + Changes the type of easing of the key frame + + .. lua:attribute:: strength: number + + Changes the strength of the easing + + .. lua:attribute:: loopAmount: integer + + Changes amount of previous frames that are looped + 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..fb55976 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 ######## @@ -153,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 @@ -169,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 @@ -203,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 ######## @@ -469,3 +526,130 @@ 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: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 + +.. 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 + + 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..46ad134 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) @@ -164,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`` @@ -185,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 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 ==================