diff --git a/docs/source/api/color.rst b/docs/source/api/color.rst index 70b81e6..6a0fb9c 100644 --- a/docs/source/api/color.rst +++ b/docs/source/api/color.rst @@ -27,19 +27,27 @@ color .. lua:attribute:: r: number The red component of the color + + .. helptext:: get or set the red component .. lua:attribute:: g: number The green component of the color + .. helptext:: get or set the green component + .. lua:attribute:: b: number The blue component of the color + .. helptext:: get or set the blue component + .. lua:attribute:: a: number The alpha component of the color + .. helptext:: get or set the alpha component + .. lua:method:: linear() -> color Returns the color converted to linear space @@ -80,17 +88,39 @@ color ***************** .. lua:attribute:: black: const + + .. helptext:: predefined black color constant .. lua:attribute:: white: const + + .. helptext:: predefined white color constant .. lua:attribute:: clear: const + + .. helptext:: predefined clear (transparent) color constant .. lua:attribute:: cyan: const + + .. helptext:: predefined cyan color constant .. lua:attribute:: gray: const + + .. helptext:: predefined gray color constant .. lua:attribute:: grey: const + + .. helptext:: predefined grey color constant .. lua:attribute:: red: const + + .. helptext:: predefined red color constant .. lua:attribute:: green: const + + .. helptext:: predefined green color constant .. lua:attribute:: blue: const + + .. helptext:: predefined blue color constant .. lua:attribute:: magenta: const + + .. helptext:: predefined magenta color constant .. lua:attribute:: yellow: const + .. helptext:: predefined yellow color constant + Color operators *************** diff --git a/docs/source/api/entity.rst b/docs/source/api/entity.rst index 1418a52..3615c34 100644 --- a/docs/source/api/entity.rst +++ b/docs/source/api/entity.rst @@ -18,18 +18,26 @@ entity .. literalinclude:: /code/Example_entity_active.codea/Main.lua :language: lua + .. helptext:: get or set the active state of this entity + .. lua:attribute:: activeInHierarchy: boolean [readonly] The computed active in hierarchy state of this entity. Only ``true`` when all parents up to the root are active as well + .. helptext:: get the computed active state in the hierarchy + .. lua:attribute:: valid: boolean Checks the validity of this entity. When an entity is destroyed it is invalid and can no longer be used. non-valid entities will raise errors when calling functions or accessing properties + .. helptext:: get whether this entity is valid + .. lua:attribute:: id: integer A read-only identifier unique to the entity + .. helptext:: get the unique identifier of this entity + .. lua:attribute:: name: string The name of the entity, useful when referring to the entity later using the :lua:class:`scene` and :lua:class:`entity` indexers @@ -40,6 +48,8 @@ entity scene.main:entity("ball") -- create a new entity named 'ball' print(scene.main.ball) -- retrieve the entity named 'ball' + .. helptext:: get or set the name of this entity + **Lifecycle** .. lua:method:: destroy([delay]) @@ -132,6 +142,8 @@ entity Retrieves a list of all components attached to this entity + .. helptext:: get all components attached to this entity + .. lua:method:: dispatch(name, ...) Calls the method ``name`` on this entity (including any custom methods) and any attached custom lua components. Additional arguments will be passed to the method as well @@ -147,22 +159,32 @@ entity The parent of this entity or ``nil`` if it is a root entity + .. helptext:: get or set the parent of this entity + .. lua:attribute:: root: entity The root parent entity in the scene heirarchy (or self if this entity has no parent) + .. helptext:: get the root entity in the hierarchy + .. lua:attribute:: children: table A list of all immediate children of this entity + .. helptext:: get all immediate children of this entity + .. lua:attribute:: childCount: integer The number of children that this entity possesses + .. helptext:: get the number of children of this entity + .. lua:attribute:: depth: integer The depth of this entity in the hierarchy (roots have a depth of 0) + .. helptext:: get the depth of this entity in the hierarchy + .. lua:method:: index(name) [metamethod] Retrieves children with the supplied name using the property syntax (i.e. ``myEntity.theChildName``) @@ -211,78 +233,116 @@ entity The position of the entity in local 3D space + .. helptext:: get or set the local position of this entity + .. lua:attribute:: worldPosition: vec3 The position of the entity in global 3D space + .. helptext:: get or set the world position of this entity + .. lua:attribute:: scale: vec3 The scale of the entity in local 3D space + .. helptext:: get or set the scale of this entity + .. lua:attribute:: uniformScale: number The uniform scale of the entity in local 3D space + .. helptext:: get or set the uniform local scale of this entity + .. lua:attribute:: rotation: quat The rotation of the entity in local 3D space + .. helptext:: get or set the local rotation of this entity + .. lua:attribute:: worldRotation: quat The rotation of the entity in world 3D space + .. helptext:: get or set the world rotation of this entity + .. lua:attribute:: eulerRotation: vec3 The euler rotation of the entity in local 3D space (in degrees) + .. helptext:: get or set the local euler rotation in degrees + .. lua:attribute:: x: number The x position of the entity in local 3D space + .. helptext:: get or set the local x position + .. lua:attribute:: y: number The y position of the entity in local 3D space + .. helptext:: get or set the local y position + .. lua:attribute:: z: number The z position of the entity in local 3D space + .. helptext:: get or set the local z position + .. lua:attribute:: sx: number The x scale of the entity in local 3D space + .. helptext:: get or set the local x scale + .. lua:attribute:: sy: number The y scale of the entity in local 3D space + .. helptext:: get or set the local y scale + .. lua:attribute:: sz: number The z scale of the entity in local 3D space + .. helptext:: get or set the local z scale + .. lua:attribute:: rx: number The euler rotation around the local x axis of the entity in degrees + .. helptext:: get or set the local x euler rotation in degrees + .. lua:attribute:: ry: number The euler rotation around the local y axis of the entity in degrees + .. helptext:: get or set the local y euler rotation in degrees + .. lua:attribute:: rz: number The euler rotation around the local z axis of the entity in degrees + .. helptext:: get or set the local z euler rotation in degrees + .. lua:attribute:: forward: number The positive z axis of this entity's coordinate space transformed into world space + .. helptext:: get the forward direction in world space + .. lua:attribute:: right: number The positive x axis of this entity's coordinate space transformed into world space + .. helptext:: get the right direction in world space + .. lua:attribute:: up: number The positive y axis of this entity's coordinate space transformed into world space + .. helptext:: get the up direction in world space + .. lua:method:: transformPoint(localPoint) Transform a point from local to world space @@ -333,38 +393,54 @@ entity The sprite (``image.slice``) attached to this entity. This will be drawn at the entities' transform within the scene + .. helptext:: get or set the sprite attached to this entity + .. lua:attribute:: color: color The tint color to use + .. helptext:: get or set the tint color of this entity + .. lua:attribute:: visible: boolean Sets/gets whether the entity should be drawn or not + .. helptext:: get or set whether this entity is visible + .. lua:attribute:: flipX: boolean Flips the sprite on the x-axis + .. helptext:: get or set whether the sprite is flipped on x + .. lua:attribute:: flipY: boolean Flips the sprite on the y-axis + .. helptext:: get or set whether the sprite is flipped on y + **Mesh Properties** .. lua:attribute:: mesh: mesh The mesh attached to this entity. This will be drawn the entities' transform within the scene + .. helptext:: get or set the mesh attached to this entity + .. lua:attribute:: material: material The material attached to this entity (used in conjunction with meshes/sprites) + .. helptext:: get or set the material attached to this entity + **UI Properties / Methods** .. lua:attribute:: size: vec2 The size of the UI element + .. helptext:: get or set the size of the UI element + .. lua:attribute:: anchorX: enum The horizontal anchoring of this UI element within its parent coordinate system @@ -376,6 +452,8 @@ entity * ``RIGHT`` * ``STRETCH`` + .. helptext:: get or set the horizontal anchor of this UI element + .. lua:attribute:: anchorY: enum The vertical anchoring of this UI element within its parent coordinate system @@ -387,50 +465,72 @@ entity * ``BOTTOM`` * ``STRETCH`` + .. helptext:: get or set the vertical anchor of this UI element + .. lua:attribute:: pivot: vec2 The pivot point, representing the center of the UI element (in normalized coordinates) + .. helptext:: get or set the pivot point of this UI element + .. lua:attribute:: clip: boolean When enabled, clips drawing to within the bounds of the UI element + .. helptext:: get or set whether clipping is enabled + **Physics2D Properties** .. lua:attribute:: body2d: physics2d.body The attached 2D physics body (if there is one) + .. helptext:: get the attached 2D physics body + .. lua:attribute:: collider2d: physics2d.collider The first attached 2D physics collider (if there is one) + .. helptext:: get the first attached 2D physics collider + .. lua:attribute:: colliders2d: table All attached 2D physics colliders + .. helptext:: get all attached 2D physics colliders + .. lua:attribute:: joints2d: table All attached 2D physics joints + .. helptext:: get all attached 2D physics joints + **Physics3D Properties** .. lua:attribute:: body3d: physics3d.body The attached 3D physics body (if there is one) + .. helptext:: get the attached 3D physics body + .. lua:attribute:: collider3d: physics3d.collider The first attached 3D physics collider (if there is one) + .. helptext:: get the first attached 3D physics collider + .. lua:attribute:: colliders3d: table All attached 3D physics colliders + .. helptext:: get all attached 3D physics colliders + .. lua:attribute:: joints3d: table All attached 3D physics joints + .. helptext:: get all attached 3D physics joints + **Lifecycle Callbacks** A series of handy callbacks that can be set which will be invoked automatically by scene systems @@ -458,30 +558,42 @@ entity local ent = main.scene:entity() ent:add(SelfDestructor, 3) -- prints "I will self destruct in 3 seconds" + .. helptext:: callback invoked when this entity is created + .. lua:attribute:: destroyed: function Callback for the `destroyed()` event, which is called right before the entity is destroyed + .. helptext:: callback invoked before this entity is destroyed + **Physics Callbacks** .. lua:attribute:: collisionBegan2d: function Callback for the ``collisionBegan2d(contact)`` event, which is called when a collision occurs with a `physics2d.body` attached to this entity + .. helptext:: callback invoked when a 2D collision begins + .. lua:attribute:: collisionBegan3d: function Callback for the ``collisionBegan3d(contact)`` event, which is called when a collision occurs with a `physics3d.body` attached to this entity + .. helptext:: callback invoked when a 3D collision begins + **Simulation Callbacks** .. lua:attribute:: update: function Callback for the ``update(dt)`` event, which is called on all active entities once per frame. The ``dt`` parameter passes the delta time of the enclosing scene for this frame + .. helptext:: callback invoked once per frame + .. lua:attribute:: fixedUpdate: function Callback for the ``fixedUpdate(dt)`` event, which is called on all active entities once per fixed update (called a fixed number of times per second). The ``dt`` parameter passes the fixed delta time of the enclosing scene + .. helptext:: callback invoked once per fixed update + **Interaction Callbacks** @@ -491,7 +603,11 @@ entity During the ``BEGAN`` phase of an incomming touch, returning true from this function will capture the touch for all subsequent events, otherwise the touch will be `lost` + .. helptext:: callback invoked when a touch event occurs + .. lua:attribute:: hitTest: boolean [default = false] Enables hit testing for the ``touched(touch)`` event, which will filter touches based on collision checks using attached physics components on the main camera + .. helptext:: enable hit testing for touch events + diff --git a/docs/source/api/image.rst b/docs/source/api/image.rst index 5d6ef34..38a7c52 100644 --- a/docs/source/api/image.rst +++ b/docs/source/api/image.rst @@ -103,42 +103,62 @@ Image The width of the image in pixels + .. helptext:: get the width of this image in pixels + .. lua:attribute:: height: integer The height of the image in pixels + .. helptext:: get the height of this image in pixels + .. lua:attribute:: depth: integer The depth of the image in pixels (for volume images) + .. helptext:: get the depth of this image in pixels + .. lua:attribute:: numLayers: integer The number of layers in this image + .. helptext:: get the number of layers in this image + .. lua:attribute:: hasMips: boolean Whether this image has mip mapping or not + .. helptext:: get whether this image has mip mapping + .. lua:attribute:: cubeMap: boolean Whether this image is a cube or not + .. helptext:: get whether this image is a cube map + .. lua:attribute:: numMips: integer The number of mips this image has + .. helptext:: get the number of mips in this image + .. lua:attribute:: sampler: samplerState The sampler state for this image, which determines how texels are sampled by shaders + .. helptext:: get or set the sampler state for this image + .. lua:attribute:: smooth: boolean Sets/gets whether this image has linear or nearest filtering + .. helptext:: enable or disable smooth filtering + .. lua:attribute:: key: assetKey The asset key for this image (if it has one) + .. helptext:: get the asset key for this image + .. lua:method:: generateIrradiance(samples) Generates a guassian pyramid of pre-computed irradiance levels, used for image based lighting @@ -406,26 +426,38 @@ The ``mip`` property controls how mipmapping is handled, ``linear`` will blend b The minification filter, can be ``point``, ``linear`` or ``none`` + .. helptext:: get or set the minification filter mode + .. lua:attribute:: mag: filterMode The magnification filter, can be ``point``, ``linear`` or ``none`` + .. helptext:: get or set the magnification filter mode + .. lua:attribute:: mip: filterMode The mip filter, can be ``point``, ``linear`` or ``none`` + .. helptext:: get or set the mip filter mode + .. lua:attribute:: u: samplerMode The u sampler mode, can be ``repeat``, ``clamp`` or ``mirror`` + .. helptext:: get or set the u sampler wrap mode + .. lua:attribute:: v: samplerMode The v sampler mode, can be ``repeat``, ``clamp`` or ``mirror`` + .. helptext:: get or set the v sampler wrap mode + .. lua:attribute:: w: samplerMode The w sampler mode, can be ``repeat``, ``clamp`` or ``mirror`` + .. helptext:: get or set the w sampler wrap mode + Slices and Atlases ------------------- @@ -524,11 +556,15 @@ Slices and Atlases .. lua:attribute:: image: image The image this slice is derived from + + .. helptext:: get the source image for this slice .. lua:attribute:: atlas: atlas The atlas this slice is part of + .. helptext:: get the atlas this slice is part of + .. lua:class:: atlas A collection of ``image.slice`` objects generated from an image diff --git a/docs/source/api/input.rst b/docs/source/api/input.rst index ec963e6..fa5cc32 100644 --- a/docs/source/api/input.rst +++ b/docs/source/api/input.rst @@ -16,6 +16,8 @@ Touches An id that can be used to uniquely identify the touch + .. helptext:: get the unique identifier of this touch + .. lua:attribute:: state: enum The current state of the touch, can be: @@ -25,6 +27,8 @@ Touches * ``ENDED`` - the touch ended this frame * ``CANCELLED`` - the touch was cancelled (usually by another view or gesture recognizer) + .. helptext:: get the current state of this touch or gesture + .. lua:attribute:: type: enum The type of touch, can be: @@ -34,78 +38,116 @@ Touches * ``touch.pencil`` - a touch resulting from the pencil * ``touch.pointer`` - a touch resulting from a button based device + .. helptext:: get the type of this touch + .. lua:attribute:: x: number The x position of the touch (in screen coordinates) + .. helptext:: get the x position of this touch + .. lua:attribute:: y: number The y position of the touch (in screen coordinates) + .. helptext:: get the y position of this touch + .. lua:attribute:: prevX: number The previous x position of the touch (in screen coordinates) + .. helptext:: get the previous x position + .. lua:attribute:: prevY: number The previous y position of the touch (in screen coordinates) + .. helptext:: get the previous y position + .. lua:attribute:: deltaX: number The x position delta of the touch (in screen coordinates) + .. helptext:: get the delta x movement + .. lua:attribute:: deltaY: number The y position delta of the touch (in screen coordinates) + .. helptext:: get the delta y movement + .. lua:attribute:: pos: vec2 The position of the touch (in screen coordinates) as a vector + .. helptext:: get the position as a vec2 + .. lua:attribute:: prevPos: vec2 The previous position of the touch (in screen coordinates) as a vector - .. lua:attribute:: delta: number + .. helptext:: get the previous position as a vec2 + + .. lua:attribute:: delta: vec2 The position delta of the touch (in screen coordinates) as a vector + .. helptext:: get the delta movement + .. lua:attribute:: force: number The amount of force being applied (only applies to pencil type touches) + .. helptext:: get the force of this touch + .. lua:attribute:: maxForce: number The maximum amount of force that can be applied (only applies to pencil type touches) + .. helptext:: get the maximum force of this touch + .. lua:attribute:: timestamp: number The time when this touch event occured (only applies to pencil type touches) + .. helptext:: get the timestamp of this touch + .. lua:attribute:: azimuth: number The azimuth angle of the pencil (only applies to pencil type touches) + + .. helptext:: get the azimuth angle of the stylus .. lua:attribute:: altitude: number The altitude angle of the pencil + .. helptext:: get the altitude angle of the stylus + .. lua:attribute:: radiusTolerance: number The amount the estimated radius can vary due to hardware tolerances + .. helptext:: get the radius tolerance of this touch + .. lua:attribute:: radius: number The estimated radius of the touch + .. helptext:: get the radius of this touch + .. lua:attribute:: precisePos: vec2 The precise location of the touch (if available) + .. helptext:: get the precise position of this touch + .. lua:attribute:: precisePrevPos: vec2 The previous precise location of the touch (if available) + .. helptext:: get the precise previous position of this touch + Gestures ######## @@ -117,42 +159,62 @@ Gestures The current state of the gesture + .. helptext:: get the current state of this touch or gesture + .. lua:attribute:: location: vec2 The location of the gesture event on the screen + .. helptext:: get the location of this gesture + .. lua:attribute:: translation: vec2 The translation of the gesture event relative to its starting location + .. helptext:: get the translation of this gesture or joint + .. lua:attribute:: delta: vec2 The delta of the gesture event since last update + .. helptext:: get the delta movement + .. lua:attribute:: pinchScale: number The scale of a pinch gesture relative to its starting distance + .. helptext:: get the pinch scale of this gesture + .. lua:attribute:: pinchDelta: number The delta of the pinch distance since last update + .. helptext:: get the pinch delta of this gesture + .. lua:attribute:: pinchVelocity: number The current change in pinch distance over time + .. helptext:: get the pinch velocity of this gesture + .. lua:attribute:: rotationAngle: number The current angle of a rotation gesture relative to its' starting angle + .. helptext:: get the rotation angle of this gesture + .. lua:attribute:: rotationVelocity: number The current change in rotation angle over time + .. helptext:: get the rotation velocity of this gesture + .. lua:attribute:: touchCount: integer The current number of touches associated with this gesture + .. helptext:: get the touch count for this gesture + .. lua:class:: gesture.tap Tap gesture recognizer (using system gesture recognizer for implementation) @@ -286,107 +348,303 @@ Constants - Key Codes ********************* .. lua:attribute:: leftAlt: const + + .. helptext:: left alt key constant .. lua:attribute:: rightAlt: const + + .. helptext:: right alt key constant .. lua:attribute:: alt: const + + .. helptext:: alt key constant .. lua:attribute:: leftCtrl: const + + .. helptext:: left ctrl key constant .. lua:attribute:: rightCtrl: const + + .. helptext:: right ctrl key constant .. lua:attribute:: ctrl: const + + .. helptext:: ctrl key constant .. lua:attribute:: leftCmd: const + + .. helptext:: left command key constant .. lua:attribute:: rightCmd: const + + .. helptext:: right command key constant .. lua:attribute:: cmd: const + + .. helptext:: command key constant .. lua:attribute:: leftShift: const + + .. helptext:: left shift key constant .. lua:attribute:: rightShift: const + + .. helptext:: right shift key constant .. lua:attribute:: shift: const + + .. helptext:: shift key constant .. lua:attribute:: esc: const + + .. helptext:: escape key constant .. lua:attribute:: enter: const The return key + + .. helptext:: enter key constant .. lua:attribute:: tab: const + + .. helptext:: tab key constant .. lua:attribute:: space: const + + .. helptext:: space key constant .. lua:attribute:: backspace: const + + .. helptext:: backspace key constant .. lua:attribute:: up: const + + .. helptext:: up arrow key constant .. lua:attribute:: down: const + + .. helptext:: down arrow key constant .. lua:attribute:: left: const + + .. helptext:: left arrow key constant .. lua:attribute:: right: const + + .. helptext:: right arrow key constant .. lua:attribute:: insert: const + + .. helptext:: insert key constant .. lua:attribute:: delete: const + + .. helptext:: delete key constant .. lua:attribute:: home: const + + .. helptext:: home key constant .. lua:attribute:: end: const + + .. helptext:: end key constant .. lua:attribute:: pageup: const + + .. helptext:: page up key constant .. lua:attribute:: pagedown: const + + .. helptext:: page down key constant .. lua:attribute:: print: const + + .. helptext:: print key constant .. lua:attribute:: plus: const + + .. helptext:: plus key constant .. lua:attribute:: minus: const + + .. helptext:: minus key constant .. lua:attribute:: leftbracket: const + + .. helptext:: left bracket key constant .. lua:attribute:: rightbracket: const + + .. helptext:: right bracket key constant .. lua:attribute:: semicolon: const + + .. helptext:: semicolon key constant .. lua:attribute:: quote: const + + .. helptext:: quote key constant .. lua:attribute:: comma: const + + .. helptext:: comma key constant .. lua:attribute:: period: const + + .. helptext:: period key constant .. lua:attribute:: slash: const + + .. helptext:: forward slash key constant .. lua:attribute:: backslash: const + + .. helptext:: backslash key constant .. lua:attribute:: nonUSBackslash: const + + .. helptext:: non-US backslash key constant .. lua:attribute:: tilde: const + + .. helptext:: tilde key constant .. lua:attribute:: f1: const + + .. helptext:: F1 key constant .. lua:attribute:: f2: const + + .. helptext:: F2 key constant .. lua:attribute:: f3: const + + .. helptext:: F3 key constant .. lua:attribute:: f4: const + + .. helptext:: F4 key constant .. lua:attribute:: f5: const + + .. helptext:: F5 key constant .. lua:attribute:: f6: const + + .. helptext:: F6 key constant .. lua:attribute:: f7: const + + .. helptext:: F7 key constant .. lua:attribute:: f8: const + + .. helptext:: F8 key constant .. lua:attribute:: f9: const + + .. helptext:: F9 key constant .. lua:attribute:: f10: const + + .. helptext:: F10 key constant .. lua:attribute:: f11: const + + .. helptext:: F11 key constant .. lua:attribute:: f12: const + + .. helptext:: F12 key constant .. lua:attribute:: numpad0: const + + .. helptext:: numpad 0 key constant .. lua:attribute:: numpad1: const + + .. helptext:: numpad 1 key constant .. lua:attribute:: numpad2: const + + .. helptext:: numpad 2 key constant .. lua:attribute:: numpad3: const + + .. helptext:: numpad 3 key constant .. lua:attribute:: numpad4: const + + .. helptext:: numpad 4 key constant .. lua:attribute:: numpad5: const + + .. helptext:: numpad 5 key constant .. lua:attribute:: numpad6: const + + .. helptext:: numpad 6 key constant .. lua:attribute:: numpad7: const + + .. helptext:: numpad 7 key constant .. lua:attribute:: numpad8: const + + .. helptext:: numpad 8 key constant .. lua:attribute:: numpad9: const + + .. helptext:: numpad 9 key constant .. lua:attribute:: num0: const + + .. helptext:: 0 number key constant .. lua:attribute:: num1: const + + .. helptext:: 1 number key constant .. lua:attribute:: num2: const + + .. helptext:: 2 number key constant .. lua:attribute:: num3: const + + .. helptext:: 3 number key constant .. lua:attribute:: num4: const + + .. helptext:: 4 number key constant .. lua:attribute:: num5: const + + .. helptext:: 5 number key constant .. lua:attribute:: num6: const + + .. helptext:: 6 number key constant .. lua:attribute:: num7: const + + .. helptext:: 7 number key constant .. lua:attribute:: num8: const + + .. helptext:: 8 number key constant .. lua:attribute:: num9: const + + .. helptext:: 9 number key constant .. lua:attribute:: a: const + + .. helptext:: A key constant .. lua:attribute:: b: const + + .. helptext:: B key constant .. lua:attribute:: c: const + + .. helptext:: C key constant .. lua:attribute:: d: const + + .. helptext:: D key constant .. lua:attribute:: e: const + + .. helptext:: E key constant .. lua:attribute:: f: const + + .. helptext:: F key constant .. lua:attribute:: g: const + + .. helptext:: G key constant .. lua:attribute:: h: const + + .. helptext:: H key constant .. lua:attribute:: i: const + + .. helptext:: I key constant .. lua:attribute:: j: const + + .. helptext:: J key constant .. lua:attribute:: k: const + + .. helptext:: K key constant .. lua:attribute:: l: const + + .. helptext:: L key constant .. lua:attribute:: m: const + + .. helptext:: M key constant .. lua:attribute:: n: const + + .. helptext:: N key constant .. lua:attribute:: o: const + + .. helptext:: O key constant .. lua:attribute:: p: const + + .. helptext:: P key constant .. lua:attribute:: q: const + + .. helptext:: Q key constant .. lua:attribute:: r: const + + .. helptext:: R key constant .. lua:attribute:: s: const + + .. helptext:: S key constant .. lua:attribute:: t: const + + .. helptext:: T key constant .. lua:attribute:: u: const + + .. helptext:: U key constant .. lua:attribute:: v: const + + .. helptext:: V key constant .. lua:attribute:: w: const + + .. helptext:: W key constant .. lua:attribute:: x: const + + .. helptext:: X key constant .. lua:attribute:: y: const + + .. helptext:: Y key constant .. lua:attribute:: z: const + .. helptext:: Z key constant + Gamepad ####### @@ -398,100 +656,176 @@ Gamepad A list of all currently connected gamepads + .. helptext:: get all connected gamepads + .. lua:attribute:: current: gamepad The current main active gamepad (or nil if none connected) + .. helptext:: get the current active gamepad + .. lua:attribute:: virtual: gamepad.virtualGamepad Gets or creates a virtual gamepad which will substitute on-screen controls if no controller is currently connected + .. helptext:: get the virtual gamepad + .. lua:attribute:: connected: function(gamepad) Callback for when a gamepad is connected + .. helptext:: callback invoked when a gamepad connects + .. lua:attribute:: disconnected: function(gamepad) Callback for when a gamepad is disconnected + .. helptext:: callback invoked when a gamepad disconnects + .. lua:attribute:: leftShoulder: gamepad.button The left shoulder button + .. helptext:: get the left shoulder button + .. lua:attribute:: rightShoulder: gamepad.button The right shoulder button + .. helptext:: get the right shoulder button + .. lua:attribute:: leftTrigger: gamepad.button The left trigger + .. helptext:: get the left trigger button + .. lua:attribute:: rightTrigger: gamepad.button The right trigger + .. helptext:: get the right trigger button + .. lua:attribute:: dpad: gamepad.directionalPad + .. helptext:: get the directional pad + .. lua:attribute:: leftStick: gamepad.directionalPad + .. helptext:: get the left analog stick + .. lua:attribute:: rightStick: gamepad.directionalPad + .. helptext:: get the right analog stick + .. lua:attribute:: leftStickButton: gamepad.button + .. helptext:: get the left stick click button + .. lua:attribute:: rightStickButton: gamepad.button + .. helptext:: get the right stick click button + .. lua:attribute:: a: gamepad.button + .. helptext:: get the a button + .. lua:attribute:: b: gamepad.button + .. helptext:: get the b button + .. lua:attribute:: x: gamepad.button + .. helptext:: get the x button + .. lua:attribute:: y: gamepad.button + .. helptext:: get the y button + .. lua:attribute:: home: gamepad.button + .. helptext:: get the home button + .. lua:attribute:: menu: gamepad.button + .. helptext:: get the menu button + .. lua:attribute:: options: gamepad.button + .. helptext:: get the options button + .. lua:attribute:: touchpadButton: gamepad.button - .. lua:attribute:: touchpadSurface: gamepad.directionalPad + .. helptext:: get the touchpad button .. lua:attribute:: touchpadSurface: gamepad.directionalPad + .. helptext:: get the touchpad surface + .. lua:attribute:: batteryLevel: number + .. helptext:: get the battery level of the gamepad + .. lua:attribute:: batteryState: const + .. helptext:: get the battery state of the gamepad + .. lua:attribute:: light: color + .. helptext:: get or set the gamepad light color + .. lua:class:: button .. lua:attribute:: pressing: boolean + .. helptext:: get whether this button is being pressed + .. lua:attribute:: pressed: boolean + .. helptext:: get whether this button was just pressed + .. lua:attribute:: released: boolean + .. helptext:: get whether this button was just released + .. lua:attribute:: value: number + .. helptext:: get the analog value of this button + .. lua:attribute:: touching: boolean + .. helptext:: get whether the touchpad is being touched + .. lua:class:: directionalPad .. lua:attribute:: pressing: boolean + .. helptext:: get whether this button is being pressed + .. lua:attribute:: dir: vec2 + .. helptext:: get the direction as a vec2 + .. lua:attribute:: x: number + .. helptext:: get the x value of the directional pad + .. lua:attribute:: y: number + .. helptext:: get the y value of the directional pad + .. lua:attribute:: left: boolean + .. helptext:: get if the directional pad is moved left + .. lua:attribute:: right: boolean + .. helptext:: get if the directional pad is moved right + .. lua:attribute:: up: boolean + .. helptext:: get if the directional pad is moved up + .. lua:attribute:: down: boolean + + .. helptext:: get if the directional pad is moved down diff --git a/docs/source/api/light.rst b/docs/source/api/light.rst index 5271f18..b22682d 100644 --- a/docs/source/api/light.rst +++ b/docs/source/api/light.rst @@ -92,61 +92,89 @@ Casts a light source onto the 3D environment. Can be used with basic immediate m * `SPOT` * `ENVIRONMENT` + .. helptext:: get or set the type of light + .. lua:attribute:: intensity: number The intensity of the light source + .. helptext:: get or set the intensity of the light + .. lua:attribute:: color: color The color of the light source + .. helptext:: get or set the light color + .. lua:attribute:: castShadows: boolean Enables/disables shadow casting. Cascaded shadow mapping works for a single directional light source *note: shadows currently only work with directional lights* + .. helptext:: get or set whether the light casts shadows + .. lua:attribute:: shadowOptions: light.shadowOptions [readonly] Get the shadow options for this light *note: shadows currently only work with directional lights* + .. helptext:: get the shadow options for this light + .. lua:class:: shadowOptions .. lua:attribute:: cascades: integer The number of shadow cascades to used in rendering. The maximum number of cascades is 5 + .. helptext:: get or set the number of shadow cascades + .. lua:attribute:: size: integer The size of the cascade textures to use when rendering. High values result in more detailed shadows at the cost of memory and rendering performance + + .. helptext:: get or set the shadow map size .. lua:attribute:: constantBias: number This attribute represents the constant bias applied to the depth values during shadow map comparisons. It helps in reducing self-shadowing artifacts by offsetting the comparison depth slightly. The default value is set to 0.001 + .. helptext:: get or set the constant shadow bias + .. lua:attribute:: normalBias: number This attribute denotes the normal bias applied during shadow map comparisons. Normal bias helps in mitigating surface acne by adjusting the depth comparison based on surface normals. The default value is set to 0.1 + .. helptext:: get or set the normal shadow bias + .. lua:attribute:: far: number The far clipping plane distance for the shadow map rendering. It defines the maximum distance up to which shadows will be calculated. The default value is set to 0.0, implying no limit by default + .. helptext:: get or set the far shadow distance + .. lua:attribute:: nearHint: number A hint for the near clipping plane distance for shadow map rendering. It suggests the minimum distance from the camera to start shadow map calculations efficiently. The default value is set to 1 + .. helptext:: get or set the near shadow distance hint + .. lua:attribute:: farHint: number Similar to 'nearHint', this provides a hint for the far clipping plane distance for shadow map rendering. It suggests the maximum distance from the camera for efficient shadow map calculations. The default value is set to 100 + .. helptext:: get or set the far shadow distance hint + .. lua:attribute:: polygonOffsetConstant: number [default = 0.5] This represents the constant factor used in polygon offset calculations. It adjusts the depth values of rendered polygons to resolve depth fighting issues. The default value is set to 0.5 + .. helptext:: get or set the polygon offset constant + .. lua:attribute:: polygonOffsetSlope: number [default = 2.0] Denotes the slope factor used in polygon offset calculations. It works in conjunction with the constant factor to provide precise depth adjustments for polygons. The default value is set to 2.0 + + .. helptext:: get or set the polygon offset slope diff --git a/docs/source/api/math_types.rst b/docs/source/api/math_types.rst index f2a7bd2..bd638f6 100644 --- a/docs/source/api/math_types.rst +++ b/docs/source/api/math_types.rst @@ -24,10 +24,14 @@ math types The x component of this vector + .. helptext:: get or set the x component + .. lua:attribute:: y: number The y component of this vector + .. helptext:: get or set the y component + .. lua:staticmethod:: min(v1, v2) Return a ``vec2`` containing the component-wise minimum of two vectors @@ -44,10 +48,14 @@ math types The length of this vector + .. helptext:: get the length of this vector + .. lua:attribute:: length2: number The squared length of this vector + .. helptext:: get the squared length of this vector + .. lua:method:: normalize() Normalize this vector @@ -160,22 +168,32 @@ math types The x component of this vector + .. helptext:: get or set the x component + .. lua:attribute:: y: number The y component of this vector + .. helptext:: get or set the y component + .. lua:attribute:: z: number The z component of this vector + .. helptext:: get or set the z component + .. lua:attribute:: length: number The length of this vector + .. helptext:: get the length of this vector + .. lua:attribute:: length2: number The squared length of this vector + .. helptext:: get the squared length of this vector + .. lua:method:: normalize() Normalize this vector @@ -270,26 +288,38 @@ math types The x component of this vector + .. helptext:: get or set the x component + .. lua:attribute:: y: number The y component of this vector + .. helptext:: get or set the y component + .. lua:attribute:: z: number The z component of this vector + .. helptext:: get or set the z component + .. lua:attribute:: w: number The w component of this vector + .. helptext:: get or set the w component + .. lua:attribute:: length: number The length of this vector + .. helptext:: get the length of this vector + .. lua:attribute:: length2: number The squared length of this vector + .. helptext:: get the squared length of this vector + .. lua:method:: normalize() Normalize this vector @@ -425,24 +455,34 @@ Quaternions The x component of this vector + .. helptext:: get or set the x component + .. lua:attribute:: y: number The y component of this vector + .. helptext:: get or set the y component + .. lua:attribute:: z: number The z component of this vector + .. helptext:: get or set the z component + .. lua:attribute:: w: number The w component of this vector + .. helptext:: get or set the w component + .. lua:attribute:: angles: vec3 A set of euler angles (in degrees) that generates the same rotation as this quaternion *Please note that the potential euler angles from any given quaternion are ambiguous and should not be relied upon for smooth or consistent rotations especially when interpolating them* + .. helptext:: get the euler angles of this quaternion + .. lua:method:: slerp(q, t) :param q: The other quaternion to slerp to diff --git a/docs/source/api/mesh.rst b/docs/source/api/mesh.rst index 78ea3f1..21b7405 100644 --- a/docs/source/api/mesh.rst +++ b/docs/source/api/mesh.rst @@ -85,80 +85,114 @@ mesh The mesh texture, used by the default mesh shader (and accessible to custom shaders as well) for basic surface textures + .. helptext:: get or set the texture for this mesh + .. lua:attribute:: shader: shader Custom shader for this mesh, used when ``mesh:draw()`` is invoked + .. helptext:: get or set the shader for this mesh + .. lua:attribute:: material: material The same as assigning a shader but with a material instead + .. helptext:: get or set the material for this mesh + .. lua:attribute:: submeshIndex: integer The current sub-mesh index. Useful for multi-material meshes + .. helptext:: get or set the submesh index + .. lua:attribute:: submeshCount: integer The total number of sub-meshes within this mesh + .. helptext:: get the number of submeshes + .. lua:attribute:: vertexCount: integer The total number of vertices in the currently selected sub-mesh *3.x compatiblity note: This was originally called* ``count`` + .. helptext:: get the number of vertices + .. lua:attribute:: indexCount: integer The total number of indices in the currently selected sub-mesh *3.x compatiblity note: meshes originally did not contain indices and therefore did not have an index count* + .. helptext:: get the number of indices + .. lua:attribute:: bounds: bounds.abbb The local bounds of this mesh (no scaling or rotation applied) + .. helptext:: get the axis-aligned bounding box + .. lua:attribute:: positions: table Gets/sets the positions of the mesh vertices + .. helptext:: get or set the vertex positions + .. lua:attribute:: normals: table Gets/sets the normals of the mesh vertices + .. helptext:: get or set the vertex normals + .. lua:attribute:: colors: table Gets/sets the colors of the mesh vertices + .. helptext:: get or set the vertex colors + .. lua:attribute:: uvs: table Gets/sets the uvs of the mesh vertices + .. helptext:: get or set the vertex UV coordinates + .. lua:attribute:: indices: table Gets/sets the indices of the mesh + .. helptext:: get or set the mesh indices + .. lua:attribute:: vertices: table Gets/sets the positions of the mesh vertices while also ensuring that each set of three indices match their corresponding vertices *3.x compatiblity note: works the same as the original vertices property* + .. helptext:: get or set the mesh vertices + .. lua:attribute:: texCoords: table Gets/sets the uvs of the mesh vertices *3.x compatiblity note: works the same as the uvs property for the sake of backwards compatiblity* + .. helptext:: get or set the texture coordinates + .. lua:attribute:: root: entity Meshes loaded via ``mesh.read()`` may contain sub-objects and bones used for animations, these can be accessed as entities in a simple scene-like hierarchy *WARNING: do not attempt to delete any nodes within the root as it may have unintended side effects* + .. helptext:: get the root entity of this mesh + .. lua:attribute:: animations: table Contains the list of all animations for this mesh + .. helptext:: get the animations in this mesh + **Mesh Drawing** .. lua:method:: draw([instances]) diff --git a/docs/source/api/motion.rst b/docs/source/api/motion.rst index 60e9ba3..6c9c5d9 100644 --- a/docs/source/api/motion.rst +++ b/docs/source/api/motion.rst @@ -115,18 +115,26 @@ Device Orientation The X-axis is arbitrary and the Z-axis is vertical. + .. helptext:: arbitrary x axis, vertical z reference frame + .. lua:attribute:: XArbitraryCorrectedZVertical: integer The X-axis is arbitrary and the Z-axis is vertical. The system will attempt to correct for the device's orientation. + .. helptext:: corrected arbitrary x axis, vertical z reference frame + .. lua:attribute:: XMagneticNorthZVertical: integer The X-axis points toward the magnetic north and the Z-axis is vertical. + .. helptext:: magnetic north x axis, vertical z reference frame + .. lua:attribute:: XTrueNorthZVertical: integer The X-axis points toward the true north and the Z-axis is vertical. + .. helptext:: true north x axis, vertical z reference frame + Magnetic Field Data =================== @@ -135,6 +143,8 @@ Magnetic Field Data .. lua:attribute:: field: vec3 The magnetic field vector in the device's reference frame. + + .. helptext:: get the magnetic field vector .. lua:attribute:: accuracy: integer @@ -146,3 +156,5 @@ Magnetic Field Data - ``motion.magneticAccuracy.low``: The magnetic field data is of low accuracy. - ``motion.magneticAccuracy.medium``: The magnetic field data is of medium accuracy. - ``motion.magneticAccuracy.high``: The magnetic field data is of high accuracy. + + .. helptext:: get the magnetic field accuracy diff --git a/docs/source/api/pasteboard.rst b/docs/source/api/pasteboard.rst index 1d2c399..4e3a4c8 100644 --- a/docs/source/api/pasteboard.rst +++ b/docs/source/api/pasteboard.rst @@ -14,54 +14,82 @@ type is not present, but a notification may still appear if data is accessed. The name of the pasteboard. + .. helptext:: get the name of this pasteboard + .. lua:attribute:: numberOfItems: number The number of items in the pasteboard. + .. helptext:: get the number of items on this pasteboard + .. lua:attribute:: hasStrings: boolean Whether the pasteboard contains one or more strings. + .. helptext:: get whether this pasteboard has strings + .. lua:attribute:: string: string The first string in the pasteboard. + .. helptext:: get or set the string on this pasteboard + .. lua:attribute:: strings: table A table of strings in the pasteboard. + .. helptext:: get or set the strings on this pasteboard + .. lua:attribute:: hasImages: boolean Whether the pasteboard contains one or more images. + .. helptext:: get whether this pasteboard has images + .. lua:attribute:: image: image The first image in the pasteboard. + .. helptext:: get or set the image on this pasteboard + .. lua:attribute:: images: table A table of images in the pasteboard. + .. helptext:: get or set the images on this pasteboard + .. lua:attribute:: hasColors: boolean Whether the pasteboard contains one or more colors. + .. helptext:: get whether this pasteboard has colors + .. lua:attribute:: color: color The first color in the pasteboard. + .. helptext:: get or set the color on this pasteboard + .. lua:attribute:: colors: table A table of colors in the pasteboard. + .. helptext:: get or set the colors on this pasteboard + .. lua:attribute:: hasURLs: boolean Whether the pasteboard contains one or more URLs. + .. helptext:: get whether this pasteboard has URLs + .. lua:attribute:: URL: string The first URL in the pasteboard. + .. helptext:: get or set the URL on this pasteboard + .. lua:attribute:: URLs: table A table of URLs in the pasteboard. + + .. helptext:: get or set the URLs on this pasteboard diff --git a/docs/source/api/physics2d.rst b/docs/source/api/physics2d.rst index ec49643..23b7d8c 100644 --- a/docs/source/api/physics2d.rst +++ b/docs/source/api/physics2d.rst @@ -76,6 +76,8 @@ Simulation The current gravity vector for this world + .. helptext:: get or set the 2D physics gravity vector + .. lua:class:: body A two dimensional rigidbody that simulated within a :lua:class:`physics2d.world`. Used to simulate both dynamic and static objects, responding to physical forces, collisions and physics queries (i.e. raycast, queryBox, etc...) @@ -275,78 +277,114 @@ Simulation Flag indicating that this body has already been destroyed + .. helptext:: get whether this body or collider is destroyed + .. lua:attribute:: position: vec2 The position of this body in the simulated world + .. helptext:: get or set the position of this body + .. lua:attribute:: mass: number (readonly) The mass of this body in kilograms + .. helptext:: get the mass of this body + .. lua:attribute:: inertia: number The interial tensor in kg m^2 + .. helptext:: get or set the inertia of this body + .. lua:attribute:: linearVelocity: vec2 The linear velocity of the body + .. helptext:: get or set the linear velocity + .. lua:attribute:: angularVelocity: number The angular velocity of the body + .. helptext:: get or set the angular velocity + .. lua:attribute:: linearDamping: number The amount of linear damping to apply, slowing velocity proportionally over time + .. helptext:: get or set the linear damping + .. lua:attribute:: angularDamping: number The amount of linear damping to apply, slowing rotation propotionally over time + .. helptext:: get or set the angular damping + .. lua:attribute:: gravityScale: number The scale factor to apply to global gravity, settings 0 will disable gravity + .. helptext:: get or set the gravity scale + .. lua:attribute:: bullet: boolean Continuous physics switch for this body, used to prevent tunneling for fast moving objects + .. helptext:: get or set whether bullet mode is enabled + .. lua:attribute:: sleepingAllowed: boolean Flag for allowing sleeping for this body + .. helptext:: get or set whether sleeping is allowed + .. lua:attribute:: awake: boolean Flag for the current awake state of this body, set to ``true`` to wake immediately + .. helptext:: get or set whether this body is awake + .. lua:attribute:: enabled: boolean Flag for whether simulation is enabled + .. helptext:: get or set whether this body or joint is enabled + .. lua:attribute:: fixedRotation: boolean Flag for fixed rotation state, set to ``false`` to disable rotation + .. helptext:: get or set whether rotation is fixed + .. lua:attribute:: onCollisionBegan: function A callback for when a collision with this body begins, with more information provided by the supplied :lua:class:`physics2d.contact` object + .. helptext:: callback invoked when collision begins + .. lua:attribute:: onCollisionEnded: function A callback for when a collision with this body ends, with more information provided by the supplied :lua:class:`physics2d.contact` object + .. helptext:: callback invoked when collision ends + .. lua:attribute:: onPreSolve: function A callback for when a collision with this body is about to be solved, allowing for some :lua:class:`physics2d.contact` parameters to be modified See: https://box2d.org/documentation/classb2_contact_listener.html + .. helptext:: callback invoked before collision is resolved + .. lua:attribute:: onPostSolve: function A callback for when a collision with this body has been solved, allowing for some :lua:class:`physics2d.contact` information to be used for other purposes See: https://box2d.org/documentation/classb2_contact_listener.html + .. helptext:: callback invoked after collision is resolved + Collision ######### @@ -364,22 +402,32 @@ Collision Flag indicating that this collider has already been destroyed + .. helptext:: get whether this body or collider is destroyed + .. lua:attribute:: friction: number The coefficient of friction for this collider + .. helptext:: get or set the friction coefficient + .. lua:attribute:: density: number The density of this collider + .. helptext:: get or set the density + .. lua:attribute:: restitution: number The coefficient of restitution for this collider + .. helptext:: get or set the restitution coefficient + .. lua:attribute:: sensor: boolean Flag turning this collider into a sensor. Sensors do not physically collide with object bodies but will still report collision detection via callbacks + .. helptext:: get or set whether this collider is a sensor + .. lua:attribute:: category: integer (bitfield) The category for this collider. Categories are used to filter collisions based on their ``mask`` bits @@ -403,33 +451,53 @@ Collision itemCollider.category = ITEM_CAT itemCollider.mask = PLAYER_CAT + .. helptext:: get or set the collision category bitfield + .. lua:attribute:: mask: integer (bitfield) The mask determines what categories this collider will pass collision filtering. If the mask bits are set for at least one category of a potential collision partner then a collision will be possible + .. helptext:: get or set the collision mask bitfield + .. lua:attribute:: group: integer The group index is used for another extra layer of collision filtering. If two colliders have the same group and are positive, they will always collide, and if they are both negative then they will never collide + .. helptext:: get or set the collision group + .. lua:attribute:: body: physics2d.body The body this collider belongs to + .. helptext:: get the body this collider belongs to + .. lua:class:: circle: collider .. lua:attribute:: radius: number + + .. helptext:: get or set the radius .. lua:attribute:: center: vec2 + .. helptext:: get or set the center point + .. lua:class:: box: collider .. lua:attribute:: center: vec2 + + .. helptext:: get or set the center point .. lua:attribute:: size: vec2 + + .. helptext:: get or set the size .. lua:attribute:: angle: number + .. helptext:: get or set the angle + .. lua:class:: polygon: collider .. lua:attribute:: points: table + .. helptext:: get or set the polygon points + .. lua:class:: contact Represents physical contact between two colliders during a collision @@ -440,78 +508,114 @@ Collision Useful for one way platforms (checking collision normals and conditionally disabling them) + .. helptext:: get or set whether this body or joint is enabled + .. lua:attribute:: touching: boolean Where the contact is currently touching (in some cases this may be false during collision resolution substeps) + .. helptext:: get whether these bodies are touching + .. lua:attribute:: friction: number The friction of this contact, which can be modified within the :lua:attr:`physics2d.body.onPreSolve` callback + .. helptext:: get or set the friction coefficient + .. lua:attribute:: restitution: number The restitution of this contact, which can be modified within the :lua:attr:`physics2d.body.onPreSolve` callback + .. helptext:: get or set the restitution coefficient + .. lua:attribute:: tangentSpeed: number The tangent of this contact, which can be modified within the :lua:attr:`physics2d.body.onPreSolve` callback Useful for creating things like conveyor belts which have a moving surface while remaining stationary + .. helptext:: get or set the tangent speed + .. lua:attribute:: localPoint: vec2 The local position of the contact point (averaged from the manifold) + .. helptext:: get the local contact point + .. lua:attribute:: worldPoint: vec2 The world position of the contact point (averaged from the manifold) + .. helptext:: get the world contact point + .. lua:attribute:: localNormal: vec2 The local normal of the contact point (averaged from the manifold) + .. helptext:: get the local contact normal + .. lua:attribute:: worldNormal: vec2 The world normal of the contact point (averaged from the manifold) + .. helptext:: get the world contact normal + .. lua:attribute:: body: physics2d.body The first body in this contact (the body receiving the callback) + .. helptext:: get the body this collider belongs to + .. lua:attribute:: otherBody: physics2d.body The second body involved in this collision contact + .. helptext:: get the other body in the contact + .. lua:attribute:: collider: physics2d.collider The first collider in this contact (attached to the body recieving the callback) + .. helptext:: get the collider in the contact + .. lua:attribute:: otherCollider: physics2d.collider The second collider involved in this collision contact + .. helptext:: get the other collider in the contact + .. lua:class:: rayHit .. lua:attribute:: point: vec2 The world position of the raycast hit location + .. helptext:: get the contact or raycast hit point + .. lua:attribute:: normal: vec2 The world normal of the raycast hit location + .. helptext:: get the contact or raycast hit normal + .. lua:attribute:: fraction: number The fraction of the total ray distance travelled before a hit was detected + .. helptext:: get the raycast hit fraction + .. lua:attribute:: collider: physics2d.collider The collider that was hit by the ray + .. helptext:: get the collider in the contact + .. lua:attribute:: body: physics2d.body The body of the collider that was hit by the ray + .. helptext:: get the body this collider belongs to + Constraints ########### @@ -551,34 +655,50 @@ Constraints Enable/disable this joint + .. helptext:: get or set whether this joint is enabled + .. lua:attribute:: destroyed: boolean Flag set to true if this joint has already been destroyed + .. helptext:: get whether this joint is destroyed + .. lua:attribute:: collideConnected: boolean When enabled bodies connected by a joint will collide with each other. Disabled by default + .. helptext:: get or set whether connected bodies collide + .. lua:attribute:: anchorA: vec2 The anchor point for the first body in world space + .. helptext:: get or set anchor point A in world space + .. lua:attribute:: anchorB: vec2 The anchor point for the second (attached) body in world space + .. helptext:: get or set anchor point B in world space + .. lua:attribute:: localAnchorA: vec2 The anchor point for the first body in local space + .. helptext:: get or set local anchor point A + .. lua:attribute:: localAnchorB: vec2 The anchor point for the second (attached) body in local space + .. helptext:: get or set local anchor point B + .. lua:attribute:: other: physics2d.body The other physics body attached to this joint + .. helptext:: get the other body connected by this joint + .. lua:class:: hinge: joint A hinge type joint, pinning the bodies together at the respective anchor points, while allowing for free rotation with optional motor and angular limits @@ -587,38 +707,56 @@ Constraints The initial relative angle of the two connected bodies + .. helptext:: get or set the reference angle + .. lua:attribute:: angle: number The current angle (in degrees) between the two connected bodies relative to the reference angle + .. helptext:: get or set the angle + .. lua:attribute:: speed: number The current angular speed of the joint (in degrees per second) + .. helptext:: get or set the motor speed + .. lua:attribute:: useMotor: boolean Enable/disables the joint motor (off by default) + .. helptext:: get or set whether the motor is enabled + .. lua:attribute:: maxTorque: number The maximum amount of torque to apply use the motor + .. helptext:: get or set the maximum motor torque + .. lua:attribute:: motorSpeed: number The target speed of the motor + .. helptext:: get or set the motor speed + .. lua:attribute:: useLimit: number Enables/disables angular joint limits (off by default) + .. helptext:: get or set whether limits are enabled + .. lua:attribute:: lowerLimit: number The lower angular rotation limit in degrees (when limits are enabled) + .. helptext:: get or set the lower joint limit + .. lua:attribute:: upperLimit: number The upper angular rotation limit in degrees (when limits are enabled) + .. helptext:: get or set the upper joint limit + .. lua:class:: slider: joint A sliding (prismatic) joint allowing for translation along a single axis @@ -627,49 +765,79 @@ Constraints The initial relative angle of the two connected bodies + .. helptext:: get or set the reference angle + .. lua:attribute:: translation: number The current relative translation between the two bodies along the constained axis + .. helptext:: get the joint translation + .. lua:attribute:: speed: number The current relative speed between the two bodies along the constrained axis + .. helptext:: get or set the motor speed + .. lua:attribute:: useMotor: boolean Enable/disables the joint motor (off by default) + .. helptext:: get or set whether the motor is enabled + .. lua:attribute:: maxForce: number The maximum amount of force to apply use the motor + .. helptext:: get or set the maximum motor force + .. lua:attribute:: motorSpeed: number The target speed of the motor + .. helptext:: get or set the motor speed + .. lua:attribute:: useLimit: number Enables/disables linear joint limits (off by default) + .. helptext:: get or set whether limits are enabled + .. lua:attribute:: lowerLimit: number The lower linear translation limit in meters (when limits are enabled) + .. helptext:: get or set the lower joint limit + .. lua:attribute:: upperLimit: number The upper linear translation limit in meters (when limits are enabled) + .. helptext:: get or set the upper joint limit + .. lua:class:: distance: joint A distance based joint constraint with spring-like properties and distance based limits .. lua:attribute:: length: number + + .. helptext:: get or set the rope length .. lua:attribute:: currentLength: number + + .. helptext:: get the current rope length .. lua:attribute:: stiffness: number + + .. helptext:: get or set the spring stiffness .. lua:attribute:: damping: number + + .. helptext:: get or set the spring damping .. lua:attribute:: minLength: number + + .. helptext:: get or set the minimum rope length .. lua:attribute:: maxLength: number + .. helptext:: get or set the maximum rope length + .. lua:class:: pulley: joint *Not implemented yet* diff --git a/docs/source/api/physics3d.rst b/docs/source/api/physics3d.rst index 52da9c8..cf3857d 100644 --- a/docs/source/api/physics3d.rst +++ b/docs/source/api/physics3d.rst @@ -88,6 +88,8 @@ physics3d The current gravity vector for this world + .. helptext:: get or set the 3D physics gravity vector + .. lua:class:: body A three dimensional rigidbody that simulated within a :lua:class:`physics3d.world`. Used to simulate both dynamic and static objects, responding to physical forces, collisions and physics queries (i.e. raycast, queryBox, etc...) @@ -327,38 +329,56 @@ physics3d Flag indicating that this body has already been destroyed + .. helptext:: get whether this body is destroyed + .. lua:attribute:: position: vec3 The position of this body in the simulated world + .. helptext:: get or set the position of this body + .. lua:attribute:: mass: number The mass of this body in kilograms + .. helptext:: get or set the mass of this body + .. lua:attribute:: inertia: number (readonly) The interial tensor in kg m^2 + .. helptext:: get the inertia tensor of this body + .. lua:attribute:: linearDamping: number The amount of linear damping to apply, slowing velocity proportionally over time + .. helptext:: get or set the linear damping + .. lua:attribute:: angularDamping: number The amount of linear damping to apply, slowing rotation propotionally over time + .. helptext:: get or set the angular damping + .. lua:attribute:: sleepingAllowed: boolean Flag for allowing sleeping for this body + .. helptext:: get or set whether sleeping is allowed + .. lua:attribute:: awake: boolean Flag for the current awake state of this body, set to ``true`` to wake immediately + .. helptext:: get or set whether this body is awake + .. lua:attribute:: enabled: boolean Flag for whether simulation is enabled + .. helptext:: get or set whether this body is enabled + .. lua:attribute:: constraints: bitfield Flags to lock movement and rotation along each axis, using the following flags: @@ -375,10 +395,14 @@ physics3d These flags can also be combined, i.e. ``myBody.constraints = physics3d.freezePositionX | physics3d.freezeRotation`` + .. helptext:: get or set the motion constraints bitfield + .. lua:attribute:: bullet: boolean Continuous physics switch for this body, used to prevent tunneling for fast moving objects + .. helptext:: get or set whether bullet mode is enabled + .. lua:class:: collider TODO @@ -441,30 +465,46 @@ physics3d The world position of the raycast hit location + .. helptext:: get the raycast hit point + .. lua:attribute:: normal: vec3 The world normal of the raycast hit location + .. helptext:: get the raycast hit normal + .. lua:attribute:: fraction: number The fraction of the total ray distance travelled before a hit was detected + .. helptext:: get the raycast hit fraction + .. lua:attribute:: triangleIndex: integer The index of the triangle hit (if we hit a mesh collider) + .. helptext:: get the raycast hit triangle index + .. lua:attribute:: uv: vec2 The uv coorindate of the triangle hit (if we hit a mesh collider) + .. helptext:: get the raycast hit UV coordinate + .. lua:attribute:: barycentric: vec2 The barycentric coorindate of the triangle hit (if we hit a mesh collider) + .. helptext:: get the raycast hit barycentric coordinate + .. lua:attribute:: collider: physics3d.collider The collider that was hit by the ray + .. helptext:: get the raycast hit collider + .. 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 + + .. helptext:: get the raycast hit body diff --git a/docs/source/api/pick.rst b/docs/source/api/pick.rst index d621bd1..ce3568e 100644 --- a/docs/source/api/pick.rst +++ b/docs/source/api/pick.rst @@ -143,6 +143,8 @@ Images are always copied to the project's assets and cannot be loaded as referen - ``decodeTable`` - Decode the picked asset as a table (only for json assets) - ``reference`` - Do not copy the asset to the project's assets, instead reference the original file + .. helptext:: an option value for the picker + .. lua:function:: pick(...) Pick assets with the specified UTType strings, options and callback function. diff --git a/docs/source/api/require.rst b/docs/source/api/require.rst index e0c03d8..f2cb6d9 100644 --- a/docs/source/api/require.rst +++ b/docs/source/api/require.rst @@ -46,3 +46,5 @@ require - ``loadMain`` - When used with a Codea project, load Main.lua - ``noImport`` - Do not import global variables and functions + + .. helptext:: an option value for require diff --git a/docs/source/api/shader.rst b/docs/source/api/shader.rst index 4c041ca..5e97ac5 100644 --- a/docs/source/api/shader.rst +++ b/docs/source/api/shader.rst @@ -247,6 +247,8 @@ shader .. lua:attribute:: size: integer The current size of the buffer + + .. helptext:: get the size of this shader buffer .. lua:method:: resize(size) diff --git a/docs/source/api/sound.rst b/docs/source/api/sound.rst index b9f25b7..c0654ff 100644 --- a/docs/source/api/sound.rst +++ b/docs/source/api/sound.rst @@ -9,30 +9,44 @@ The sound module provides a way to play and manage sound effects and background Procedural coin sound preset (SFXR) + .. helptext:: coin sound effect constant + .. lua:attribute:: SOUND_LASER: const Procedural laser sound preset (SFXR) + .. helptext:: laser sound effect constant + .. lua:attribute:: SOUND_EXPLOSION: const Procedural explosion sound preset (SFXR) + .. helptext:: explosion sound effect constant + .. lua:attribute:: SOUND_POWERUP: const Procedural powerup sound preset (SFXR) + .. helptext:: power-up sound effect constant + .. lua:attribute:: SOUND_HURT: const Procedural hurt sound preset (SFXR) + .. helptext:: hurt sound effect constant + .. lua:attribute:: SOUND_JUMP: const Procedural jump sound preset (SFXR) + .. helptext:: jump sound effect constant + .. lua:attribute:: SOUND_BLIP: const Procedural blip sound preset (SFXR) + .. helptext:: blip sound effect constant + .. lua:staticmethod:: play(preset[, seed]) Plays a preset procedural SFXR sound effect using a given ``preset`` and optional ``seed`` diff --git a/docs/source/api/style.rst b/docs/source/api/style.rst index ad399a2..3f121b6 100644 --- a/docs/source/api/style.rst +++ b/docs/source/api/style.rst @@ -191,15 +191,23 @@ Constants - Shape Mode .. lua:attribute:: CORNER: const + .. helptext:: corner rect mode constant + .. lua:attribute:: CORNERS: const + .. helptext:: corners rect mode constant + .. lua:attribute:: CENTER: const + .. helptext:: center mode constant + .. lua:attribute:: RADIUS: const + .. helptext:: radius mode constant + .. lua:function:: sortOrder(order) .. helptext:: set the sort order for drawing @@ -280,6 +288,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_NORMAL.png :width: 200 + .. helptext:: normal blend mode constant + .. lua:attribute:: ADDITIVE: const Additive blend mode @@ -287,6 +297,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_ADDITIVE.png :width: 200 + .. helptext:: additive blend mode constant + .. lua:attribute:: MULTIPLY: const Multiply blend mode @@ -294,6 +306,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_MULTIPLY.png :width: 200 + .. helptext:: multiply blend mode constant + .. lua:attribute:: SCREEN: const Screen blend mode @@ -301,6 +315,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_SCREEN.png :width: 200 + .. helptext:: screen blend mode constant + .. lua:attribute:: LIGHTEN: const Lighten blend mode @@ -308,6 +324,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_LIGHTEN.png :width: 200 + .. helptext:: lighten blend mode constant + .. lua:attribute:: LINEAR_BURN: const Linear burn blend mode @@ -315,6 +333,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_LINEAR_BURN.png :width: 200 + .. helptext:: linear burn blend mode constant + .. lua:attribute:: PREMULTIPLIED: const Premultiplied blend mode @@ -322,6 +342,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_PREMULTIPLIED.png :width: 200 + .. helptext:: premultiplied blend mode constant + .. lua:attribute:: DISABLED: const Disables blending @@ -329,6 +351,8 @@ Constants - Blend Modes .. image:: /images/example_blendMode_DISABLED.png :width: 200 + .. helptext:: disabled blend mode constant + Constants - Blend Functions *************************** @@ -336,22 +360,32 @@ Constants - Blend Functions Combines source and destination pixels using addition + .. helptext:: additive blend equation constant + .. lua:attribute:: EQUATION_SUB: const Combines source and destination pixels using subtraction + .. helptext:: subtractive blend equation constant + .. lua:attribute:: EQUATION_REVSUB: const Combines source and destination pixels using subtraction in reverse order + .. helptext:: reverse subtractive blend equation constant + .. lua:attribute:: EQUATION_MIN: const Combines source and destination pixels by taking the minimum of each component (ignores blend factors) + .. helptext:: minimum blend equation constant + .. lua:attribute:: EQUATION_MAX: const Combines source and destination pixels by taking the maximum of each component (ignores blend factors) + .. helptext:: maximum blend equation constant + Constants - Blend Factors ************************* @@ -359,42 +393,62 @@ Constants - Blend Factors Blend factor of :math:`(0, 0, 0, 0)` + .. helptext:: zero blend factor constant + .. lua:attribute:: ONE: const Blend factor or :math:`(1, 1, 1, 1)` + .. helptext:: one blend factor constant + .. lua:attribute:: SRC_COLOR: const Blend factor of :math:`(R_s, G_s, B_s, A_s)` + .. helptext:: source color blend factor constant + .. lua:attribute:: ONE_MINUS_SRC_COLOR: const Blend factor of :math:`(1-R_s, 1-G_s, 1-B_s, 1-A_s)` + .. helptext:: one minus source color blend factor constant + .. lua:attribute:: SRC_ALPHA: const Blend factor of :math:`(A_s, A_s, A_s, A_s)` + .. helptext:: source alpha blend factor constant + .. lua:attribute:: ONE_MINUS_SRC_ALPHA: const Blend factor of :math:`(1-A_s, 1-A_s, 1-A_s, 1-A_s)` + .. helptext:: one minus source alpha blend factor constant + .. lua:attribute:: DST_ALPHA: const Blend factor of :math:`(A_d, A_d, A_d, A_d)` + .. helptext:: destination alpha blend factor constant + .. lua:attribute:: ONE_MINUS_DST_ALPHA: const Blend factor of :math:`(1-A_d, 1-A_d, 1-A_d, 1-A_d)` + .. helptext:: one minus destination alpha blend factor constant + .. lua:attribute:: DST_COLOR: const Blend factor of :math:`(R_d, G_d, B_d, A_d)` + .. helptext:: destination color blend factor constant + .. lua:attribute:: SRC_ALPHA_SATURATE: const Blend factor of :math:`(f, f, f, 1)` where :math:`f = min(A_s, 1 - A_d)` + .. helptext:: source alpha saturate blend factor constant + Viewport ######## @@ -493,25 +547,57 @@ Used by drawing commands and shaders to control stencil operations **Stencil Test (conditions)** .. lua:attribute:: STENCIL_TEST_LESS: const + + .. helptext:: less-than stencil test constant .. lua:attribute:: STENCIL_TEST_LEQUAL: const + + .. helptext:: less-than-or-equal stencil test constant .. lua:attribute:: STENCIL_TEST_EQUAL: const + + .. helptext:: equal stencil test constant .. lua:attribute:: STENCIL_TEST_GEQUAL: const + + .. helptext:: greater-than-or-equal stencil test constant .. lua:attribute:: STENCIL_TEST_GREATER: const + + .. helptext:: greater-than stencil test constant .. lua:attribute:: STENCIL_TEST_NOTEQUAL: const + + .. helptext:: not-equal stencil test constant .. lua:attribute:: STENCIL_TEST_NEVER: const + + .. helptext:: never stencil test constant .. lua:attribute:: STENCIL_TEST_ALWAYS: const + .. helptext:: always stencil test constant + **Stencil Operations (pass, fail, zfail)** .. lua:attribute:: STENCIL_OP_ZERO: const + + .. helptext:: zero stencil operation constant .. lua:attribute:: STENCIL_OP_KEEP: const + + .. helptext:: keep stencil operation constant .. lua:attribute:: STENCIL_OP_REPLACE: const + + .. helptext:: replace stencil operation constant .. lua:attribute:: STENCIL_OP_INCREMENT_WRAP: const + + .. helptext:: increment wrap stencil operation constant .. lua:attribute:: STENCIL_OP_INCREMENT: const + + .. helptext:: increment stencil operation constant .. lua:attribute:: STENCIL_OP_DECREMENT_WRAP: const + + .. helptext:: decrement wrap stencil operation constant .. lua:attribute:: STENCIL_OP_DECREMENT: const + + .. helptext:: decrement stencil operation constant .. lua:attribute:: STENCIL_OP_INVERT: const + .. helptext:: invert stencil operation constant + Text Style ########## @@ -532,57 +618,89 @@ Constants - Text .. lua:attribute:: LEFT: const + .. helptext:: left alignment constant + .. lua:attribute:: CENTER: const + .. helptext:: center mode constant + .. lua:attribute:: RIGHT: const + .. helptext:: right alignment constant + .. lua:attribute:: TOP: const + .. helptext:: top alignment constant + .. lua:attribute:: MIDDLE: const + .. helptext:: middle alignment constant + .. lua:attribute:: BOTTOM: const + .. helptext:: bottom alignment constant + .. lua:attribute:: BASELINE: const + .. helptext:: baseline alignment constant + Constants - Style ################# .. lua:attribute:: ROUND: const + .. helptext:: round line cap constant + .. lua:attribute:: SQUARE: const + .. helptext:: square line cap constant + .. lua:attribute:: PROJECT: const + .. helptext:: project line cap constant + .. lua:attribute:: MITER: const + .. helptext:: miter line join constant + .. lua:attribute:: BEVEL: const + .. helptext:: bevel line join constant + Constants - Render Queues ######################### .. lua:attribute:: BACKGROUND: const + .. helptext:: background pass type constant + .. lua:attribute:: OPAQUE: const + .. helptext:: opaque pass type constant + .. lua:attribute:: TRANSPARENT: const + .. helptext:: transparent pass type constant + .. lua:attribute:: OVERLAY: const + .. helptext:: overlay pass type constant + Constants - Color Mask ###################### @@ -590,24 +708,38 @@ Used by shaders to control which color components are written to color buffers ( .. lua:attribute:: COLOR_MASK_NONE: const + .. helptext:: no color channels mask constant + .. lua:attribute:: COLOR_MASK_RED: const + .. helptext:: red channel mask constant + .. lua:attribute:: COLOR_MASK_GREEN: const + .. helptext:: green channel mask constant + .. lua:attribute:: COLOR_MASK_BLUE: const + .. helptext:: blue channel mask constant + .. lua:attribute:: COLOR_MASK_ALPHA: const + .. helptext:: alpha channel mask constant + .. lua:attribute:: COLOR_MASK_RGB: const + .. helptext:: RGB channels mask constant + .. lua:attribute:: COLOR_MASK_RGBA: const + .. helptext:: all color channels mask constant + Constants - Culling ################### @@ -616,12 +748,18 @@ Used by shaders / meshes to control which triangles are culled (based on winding .. lua:attribute:: CULL_FACE_NONE: const + .. helptext:: no face culling constant + .. lua:attribute:: CULL_FACE_FRONT: const + .. helptext:: front face culling constant + .. lua:attribute:: CULL_FACE_BACK: const + .. helptext:: back face culling constant + Constants - Depth ################# @@ -629,26 +767,44 @@ Used by shaders to control depth rejection for opaque and translucent fragments .. lua:attribute:: DEPTH_WRITE_ENABLED: const + .. helptext:: depth write enabled constant + .. lua:attribute:: DEPTH_WRITE_DISABLED: const + .. helptext:: depth write disabled constant + .. lua:attribute:: DEPTH_FUNC_NEVER: const + .. helptext:: never depth function constant + .. lua:attribute:: DEPTH_FUNC_LESS: const + .. helptext:: less-than depth function constant + .. lua:attribute:: DEPTH_FUNC_EQUAL: const + .. helptext:: equal depth function constant + .. lua:attribute:: DEPTH_FUNC_LESS_EQUAL: const + .. helptext:: less-than-or-equal depth function constant + .. lua:attribute:: DEPTH_FUNC_GREATER: const + .. helptext:: greater-than depth function constant + .. lua:attribute:: DEPTH_FUNC_NOT_EQUAL: const + .. helptext:: not-equal depth function constant + .. lua:attribute:: DEPTH_FUNC_GREATER_EQUAL: const + + .. helptext:: greater-than-or-equal depth function constant diff --git a/docs/source/api/tween.rst b/docs/source/api/tween.rst index ab9e76f..406e307 100644 --- a/docs/source/api/tween.rst +++ b/docs/source/api/tween.rst @@ -39,14 +39,20 @@ Procedurally animate values over time, otherwise known as tweening The total duration of the tween in seconds + .. helptext:: get the duration of this tween + .. lua:attribute:: progress: number The current progress of the tween in seconds + + .. helptext:: get the progress of this tween .. lua:attribute:: target: object The target object being tweened + .. helptext:: get the target object of this tween + .. lua:method:: to(keyValuePairs) Creates a new tweening segement, each key is animated to the corresponding value diff --git a/docs/source/api/ui.rst b/docs/source/api/ui.rst index 6136f69..887983b 100644 --- a/docs/source/api/ui.rst +++ b/docs/source/api/ui.rst @@ -65,10 +65,14 @@ A module for creating basic UI elements in scenes The entity for this canvas + .. helptext:: get the entity associated to this canvas + .. lua:attribute:: scale: number Scale factor for canvas drawing + .. helptext:: get or set the canvas scale + .. lua:class:: label : component @@ -78,37 +82,53 @@ A module for creating basic UI elements in scenes The text to render on the label + .. helptext:: get or set the label text + .. lua:attribute:: color: color The label's text color + .. helptext:: get or set the label text color + .. lua:attribute:: fontSize: number The label's font size + .. helptext:: get or set the font size + .. lua:attribute:: align: flags The label's text alignment + .. helptext:: get or set the text alignment flags + .. lua:attribute:: style: flags The label's text style + .. helptext:: get or set the style flags or table + .. lua:attribute:: shadowOffset: vec2 The offset of the labels text shadow + .. helptext:: get or set the text shadow offset + .. lua:attribute:: shadowSoftner: number The softness of the labels text shadow + .. helptext:: get or set the text shadow softness + .. lua:class:: image : component Draws an image on a canvas entity .. lua:attribute:: image: image - The image to draw + The image to draw + + .. helptext:: get or set the image to draw .. lua:class:: button: component @@ -129,6 +149,8 @@ A module for creating basic UI elements in scenes selected = { sprite = ..., color = ... } } + .. helptext:: get or set the style flags or table + .. lua:class:: vstack: component @@ -138,10 +160,14 @@ A module for creating basic UI elements in scenes The outer padding for the stack, used to create a border around the edge + .. helptext:: get or set the padding + .. lua:attribute:: spacing: number The spacing between each item in the stack + .. helptext:: get or set the spacing + .. lua:class:: hstack: component @@ -151,6 +177,10 @@ A module for creating basic UI elements in scenes The outer padding for the stack, used to create a border around the edge + .. helptext:: get or set the padding + .. lua:attribute:: spacing: number The spacing between each item in the stack + + .. helptext:: get or set the spacing diff --git a/scripts/check_helptexts.py b/scripts/check_helptexts.py index 67b520a..30d49ce 100644 --- a/scripts/check_helptexts.py +++ b/scripts/check_helptexts.py @@ -1,14 +1,14 @@ #!/usr/bin/env python3 """ Scan all RST files under docs/source and report lua:function / -lua:method / lua:staticmethod directives that are missing a `.. helptext::` in their content block. +lua:method / lua:staticmethod / lua:attribute directives that are missing a `.. helptext::` in their content block. """ import re import sys from pathlib import Path -DIRECTIVE_RE = re.compile(r'^(\s*)\.\. lua:(function|method|staticmethod)::(.*)') +DIRECTIVE_RE = re.compile(r'^(\s*)\.\. lua:(function|method|staticmethod|attribute)::(.*)') HELPTEXT_RE = re.compile(r'\.\. helptext::') DOCS_DIR = Path(__file__).parent.parent / 'docs' / 'source'