Skip to content

Commit 4e8c676

Browse files
photonstormphotonstorm
committed
Full JSDocs coverage!
1 parent 4955602 commit 4e8c676

1 file changed

Lines changed: 114 additions & 23 deletions

File tree

‎src/physics/matter-js/Factory.js‎

Lines changed: 114 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,7 @@ var Factory = new Class({
175175
*
176176
* @param {number} x - The X coordinate of the center of the Body.
177177
* @param {number} y - The Y coordinate of the center of the Body.
178-
* @param {(string|array)} vertexSets - [description]
178+
* @param {(string|array)} vertexSets - The vertices data. Either a path string or an array of vertices.
179179
* @param {Phaser.Types.Physics.Matter.MatterBodyConfig} [options] - An optional Body configuration object that is used to set initial Body properties on creation.
180180
* @param {boolean} [flagInternal=false] - Flag internal edges (coincident part edges)
181181
* @param {number} [removeCollinear=0.01] - Whether Matter.js will discard collinear edges (to improve performance).
@@ -198,7 +198,24 @@ var Factory = new Class({
198198
},
199199

200200
/**
201-
* Creates a body using the supplied body data, as provided by an SVG file.
201+
* Creates a body using the path data from an SVG file.
202+
*
203+
* SVG Parsing requires the pathseg polyfill from https://github.com/progers/pathseg
204+
*
205+
* The SVG file should be loaded as XML, as this method requires the ability to extract
206+
* the path data from it. I.e.:
207+
*
208+
* ```javascript
209+
* preload ()
210+
* {
211+
* this.load.xml('face', 'assets/face.svg);
212+
* }
213+
*
214+
* create ()
215+
* {
216+
* this.matter.add.fromSVG(400, 300, this.cache.xml.get('face'));
217+
* }
218+
* ```
202219
*
203220
* @method Phaser.Physics.Matter.Factory#fromSVG
204221
* @since 3.22.0
@@ -413,7 +430,7 @@ var Factory = new Class({
413430
* @param {number} yOffsetA - The vertical offset of the BodyA constraint. This is a percentage based on the body size, not a world position.
414431
* @param {number} xOffsetB - The horizontal offset of the BodyB constraint. This is a percentage based on the body size, not a world position.
415432
* @param {number} yOffsetB - The vertical offset of the BodyB constraint. This is a percentage based on the body size, not a world position.
416-
* @param {object} options - An optional Constraint configuration object passed to the newly created constraints.
433+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
417434
*
418435
* @return {MatterJS.Composite} The original composite that was passed to this method.
419436
*/
@@ -432,7 +449,7 @@ var Factory = new Class({
432449
* @param {number} columns - The number of columns in the mesh.
433450
* @param {number} rows - The number of rows in the mesh.
434451
* @param {boolean} crossBrace - Create cross braces for the mesh as well?
435-
* @param {object} options - An optional Constraint configuration object passed to the newly created constraints.
452+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
436453
*
437454
* @return {MatterJS.Composite} The original composite that was passed to this method.
438455
*/
@@ -501,8 +518,8 @@ var Factory = new Class({
501518
* @param {number} rowGap - The distance between each row.
502519
* @param {boolean} crossBrace - `true` to create cross braces between the bodies, or `false` to create just straight braces.
503520
* @param {number} particleRadius - The radius of this circlular composite.
504-
* @param {object} particleOptions - [description]
505-
* @param {object} constraintOptions - [description]
521+
* @param {Phaser.Types.Physics.Matter.MatterBodyConfig} [particleOptions] - An optional Body configuration object that is used to set initial Body properties on creation.
522+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [constraintOptions] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
506523
*
507524
* @return {MatterJS.Composite} A new composite simple soft body.
508525
*/
@@ -516,7 +533,20 @@ var Factory = new Class({
516533
},
517534

518535
/**
519-
* [description]
536+
* This method is an alias for `Factory.constraint`.
537+
*
538+
* Constraints (or joints) are used for specifying that a fixed distance must be maintained
539+
* between two bodies, or a body and a fixed world-space position.
540+
*
541+
* The stiffness of constraints can be modified to create springs or elastic.
542+
*
543+
* To simulate a revolute constraint (or pin joint) set `length: 0` and a high `stiffness`
544+
* value (e.g. `0.7` or above).
545+
*
546+
* If the constraint is unstable, try lowering the `stiffness` value and / or increasing
547+
* `constraintIterations` within the Matter Config.
548+
*
549+
* For compound bodies, constraints must be applied to the parent body and not one of its parts.
520550
*
521551
* @method Phaser.Physics.Matter.Factory#joint
522552
* @since 3.0.0
@@ -525,7 +555,7 @@ var Factory = new Class({
525555
* @param {MatterJS.Body} bodyB - The second possible `Body` that this constraint is attached to.
526556
* @param {number} [length] - A Number that specifies the target resting length of the constraint. If not given it is calculated automatically in `Constraint.create` from initial positions of the `constraint.bodyA` and `constraint.bodyB`.
527557
* @param {number} [stiffness=1] - A Number that specifies the stiffness of the constraint, i.e. the rate at which it returns to its resting `constraint.length`. A value of `1` means the constraint should be very stiff. A value of `0.2` means the constraint acts as a soft spring.
528-
* @param {object} [options={}] - [description]
558+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
529559
*
530560
* @return {MatterJS.Constraint} A Matter JS Constraint.
531561
*/
@@ -535,7 +565,20 @@ var Factory = new Class({
535565
},
536566

537567
/**
538-
* [description]
568+
* This method is an alias for `Factory.constraint`.
569+
*
570+
* Constraints (or joints) are used for specifying that a fixed distance must be maintained
571+
* between two bodies, or a body and a fixed world-space position.
572+
*
573+
* The stiffness of constraints can be modified to create springs or elastic.
574+
*
575+
* To simulate a revolute constraint (or pin joint) set `length: 0` and a high `stiffness`
576+
* value (e.g. `0.7` or above).
577+
*
578+
* If the constraint is unstable, try lowering the `stiffness` value and / or increasing
579+
* `constraintIterations` within the Matter Config.
580+
*
581+
* For compound bodies, constraints must be applied to the parent body and not one of its parts.
539582
*
540583
* @method Phaser.Physics.Matter.Factory#spring
541584
* @since 3.0.0
@@ -544,7 +587,7 @@ var Factory = new Class({
544587
* @param {MatterJS.Body} bodyB - The second possible `Body` that this constraint is attached to.
545588
* @param {number} [length] - A Number that specifies the target resting length of the constraint. If not given it is calculated automatically in `Constraint.create` from initial positions of the `constraint.bodyA` and `constraint.bodyB`.
546589
* @param {number} [stiffness=1] - A Number that specifies the stiffness of the constraint, i.e. the rate at which it returns to its resting `constraint.length`. A value of `1` means the constraint should be very stiff. A value of `0.2` means the constraint acts as a soft spring.
547-
* @param {object} [options={}] - [description]
590+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
548591
*
549592
* @return {MatterJS.Constraint} A Matter JS Constraint.
550593
*/
@@ -554,7 +597,18 @@ var Factory = new Class({
554597
},
555598

556599
/**
557-
* [description]
600+
* Constraints (or joints) are used for specifying that a fixed distance must be maintained
601+
* between two bodies, or a body and a fixed world-space position.
602+
*
603+
* The stiffness of constraints can be modified to create springs or elastic.
604+
*
605+
* To simulate a revolute constraint (or pin joint) set `length: 0` and a high `stiffness`
606+
* value (e.g. `0.7` or above).
607+
*
608+
* If the constraint is unstable, try lowering the `stiffness` value and / or increasing
609+
* `constraintIterations` within the Matter Config.
610+
*
611+
* For compound bodies, constraints must be applied to the parent body and not one of its parts.
558612
*
559613
* @method Phaser.Physics.Matter.Factory#constraint
560614
* @since 3.0.0
@@ -563,7 +617,7 @@ var Factory = new Class({
563617
* @param {MatterJS.Body} bodyB - The second possible `Body` that this constraint is attached to.
564618
* @param {number} [length] - A Number that specifies the target resting length of the constraint. If not given it is calculated automatically in `Constraint.create` from initial positions of the `constraint.bodyA` and `constraint.bodyB`.
565619
* @param {number} [stiffness=1] - A Number that specifies the stiffness of the constraint, i.e. the rate at which it returns to its resting `constraint.length`. A value of `1` means the constraint should be very stiff. A value of `0.2` means the constraint acts as a soft spring.
566-
* @param {object} [options={}] - [description]
620+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
567621
*
568622
* @return {MatterJS.Constraint} A Matter JS Constraint.
569623
*/
@@ -590,15 +644,29 @@ var Factory = new Class({
590644
},
591645

592646
/**
593-
* [description]
647+
* Constraints (or joints) are used for specifying that a fixed distance must be maintained
648+
* between two bodies, or a body and a fixed world-space position.
649+
*
650+
* A world constraint has only one body, you should specify a `pointA` position in
651+
* the constraint options parameter to attach the constraint to the world.
652+
*
653+
* The stiffness of constraints can be modified to create springs or elastic.
654+
*
655+
* To simulate a revolute constraint (or pin joint) set `length: 0` and a high `stiffness`
656+
* value (e.g. `0.7` or above).
657+
*
658+
* If the constraint is unstable, try lowering the `stiffness` value and / or increasing
659+
* `constraintIterations` within the Matter Config.
660+
*
661+
* For compound bodies, constraints must be applied to the parent body and not one of its parts.
594662
*
595663
* @method Phaser.Physics.Matter.Factory#worldConstraint
596664
* @since 3.0.0
597665
*
598666
* @param {MatterJS.Body} body - The Matter `Body` that this constraint is attached to.
599667
* @param {number} [length] - A number that specifies the target resting length of the constraint. If not given it is calculated automatically in `Constraint.create` from initial positions of the `constraint.bodyA` and `constraint.bodyB`.
600668
* @param {number} [stiffness=1] - A Number that specifies the stiffness of the constraint, i.e. the rate at which it returns to its resting `constraint.length`. A value of `1` means the constraint should be very stiff. A value of `0.2` means the constraint acts as a soft spring.
601-
* @param {object} [options={}] - [description]
669+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
602670
*
603671
* @return {MatterJS.Constraint} A Matter JS Constraint.
604672
*/
@@ -624,12 +692,21 @@ var Factory = new Class({
624692
},
625693

626694
/**
627-
* [description]
695+
* This method is an alias for `Factory.pointerConstraint`.
696+
*
697+
* A Pointer Constraint is a special type of constraint that allows you to click
698+
* and drag bodies in a Matter World. It monitors the active Pointers in a Scene,
699+
* and when one is pressed down it checks to see if that hit any part of any active
700+
* body in the world. If it did, and the body has input enabled, it will begin to
701+
* drag it until either released, or you stop it via the `stopDrag` method.
702+
*
703+
* You can adjust the stiffness, length and other properties of the constraint via
704+
* the `options` object on creation.
628705
*
629706
* @method Phaser.Physics.Matter.Factory#mouseSpring
630707
* @since 3.0.0
631708
*
632-
* @param {object} options - [description]
709+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
633710
*
634711
* @return {MatterJS.Constraint} A Matter JS Constraint.
635712
*/
@@ -639,12 +716,19 @@ var Factory = new Class({
639716
},
640717

641718
/**
642-
* [description]
719+
* A Pointer Constraint is a special type of constraint that allows you to click
720+
* and drag bodies in a Matter World. It monitors the active Pointers in a Scene,
721+
* and when one is pressed down it checks to see if that hit any part of any active
722+
* body in the world. If it did, and the body has input enabled, it will begin to
723+
* drag it until either released, or you stop it via the `stopDrag` method.
724+
*
725+
* You can adjust the stiffness, length and other properties of the constraint via
726+
* the `options` object on creation.
643727
*
644728
* @method Phaser.Physics.Matter.Factory#pointerConstraint
645729
* @since 3.0.0
646730
*
647-
* @param {object} options - [description]
731+
* @param {Phaser.Types.Physics.Matter.MatterConstraintConfig} [options] - An optional Constraint configuration object that is used to set initial Constraint properties on creation.
648732
*
649733
* @return {MatterJS.Constraint} A Matter JS Constraint.
650734
*/
@@ -693,21 +777,28 @@ var Factory = new Class({
693777
},
694778

695779
/**
696-
* [description]
780+
* Creates a wrapper around a Tile that provides access to a corresponding Matter body. A tile can only
781+
* have one Matter body associated with it. You can either pass in an existing Matter body for
782+
* the tile or allow the constructor to create the corresponding body for you. If the Tile has a
783+
* collision group (defined in Tiled), those shapes will be used to create the body. If not, the
784+
* tile's rectangle bounding box will be used.
785+
*
786+
* The corresponding body will be accessible on the Tile itself via Tile.physics.matterBody.
787+
*
788+
* Note: not all Tiled collision shapes are supported. See
789+
* Phaser.Physics.Matter.TileBody#setFromTileCollision for more information.
697790
*
698791
* @method Phaser.Physics.Matter.Factory#tileBody
699792
* @since 3.0.0
700793
*
701794
* @param {Phaser.Tilemaps.Tile} tile - The target tile that should have a Matter body.
702795
* @param {Phaser.Types.Physics.Matter.MatterTileOptions} [options] - Options to be used when creating the Matter body.
703796
*
704-
* @return {Phaser.Physics.Matter.TileBody} [description]
797+
* @return {Phaser.Physics.Matter.TileBody} The Matter Tile Body Game Object.
705798
*/
706799
tileBody: function (tile, options)
707800
{
708-
var tileBody = new MatterTileBody(this.world, tile, options);
709-
710-
return tileBody;
801+
return new MatterTileBody(this.world, tile, options);
711802
},
712803

713804
/**

0 commit comments

Comments
 (0)