Skip to content

Commit 7a1c28a

Browse files
kpal81xdkpal81xd
committed
fix: mark live API getters readonly
1 parent 72fce30 commit 7a1c28a

18 files changed

Lines changed: 199 additions & 70 deletions

File tree

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@
155155
"test": "mocha --ignore \"test/assets/scripts/*.js\" --ignore \"test/bundles/**\" --recursive --require test/fixtures.mjs --timeout 5000",
156156
"test:build": "mocha --recursive \"test/bundles/**/*.test.mjs\" --timeout 30000",
157157
"test:coverage": "c8 npm test",
158-
"test:types": "tsc --pretty false build/playcanvas.d.ts"
158+
"test:types": "tsc --pretty false --noEmit build/playcanvas.d.ts test/typecheck/api-ergonomics.ts"
159159
},
160160
"engines": {
161161
"node": ">=18.3.0"

‎src/framework/components/anim/component.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -261,9 +261,10 @@ class AnimComponent extends Component {
261261
}
262262

263263
/**
264-
* Returns the animation layers available in this anim component.
264+
* Returns the animation layers available in this anim component. Use addLayer or loadStateGraph
265+
* to change layers.
265266
*
266-
* @type {AnimComponentLayer[]}
267+
* @type {ReadonlyArray<AnimComponentLayer>}
267268
*/
268269
get layers() {
269270
return this._layers;

‎src/framework/components/camera/component.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -740,7 +740,7 @@ class CameraComponent extends Component {
740740
/**
741741
* Gets the array of layer IDs ({@link Layer#id}) to which this camera belongs.
742742
*
743-
* @type {number[]}
743+
* @type {ReadonlyArray<number>}
744744
*/
745745
get layers() {
746746
return this._camera.layers;
@@ -890,7 +890,7 @@ class CameraComponent extends Component {
890890
/**
891891
* Gets the rendering rectangle for the camera.
892892
*
893-
* @type {Vec4}
893+
* @type {Readonly<Vec4>}
894894
*/
895895
get rect() {
896896
return this._camera.rect;

‎src/framework/components/collision/component.js‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -247,9 +247,10 @@ class CollisionComponent extends Component {
247247
}
248248

249249
/**
250-
* Gets the half-extents of the box-shaped collision volume in the x, y and z axes.
250+
* Gets the half-extents of the box-shaped collision volume in the x, y and z axes. Use the
251+
* setter to update the collision shape.
251252
*
252-
* @type {Vec3}
253+
* @type {Readonly<Vec3>}
253254
*/
254255
get halfExtents() {
255256
return this._halfExtents;
@@ -277,9 +278,9 @@ class CollisionComponent extends Component {
277278

278279
/**
279280
* Gets the positional offset of the collision shape from the Entity position along the local
280-
* axes.
281+
* axes. Use the setter to update the collision shape.
281282
*
282-
* @type {Vec3}
283+
* @type {Readonly<Vec3>}
283284
*/
284285
get linearOffset() {
285286
return this._linearOffset;
@@ -309,9 +310,10 @@ class CollisionComponent extends Component {
309310
}
310311

311312
/**
312-
* Gets the rotational offset of the collision shape from the Entity rotation in local space.
313+
* Gets the rotational offset of the collision shape from the Entity rotation in local space. Use
314+
* the setter to update the collision shape.
313315
*
314-
* @type {Quat}
316+
* @type {Readonly<Quat>}
315317
*/
316318
get angularOffset() {
317319
return this._angularOffset;

‎src/framework/components/element/component.js‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -434,9 +434,9 @@ class ElementComponent extends Component {
434434
}
435435

436436
/**
437-
* Gets the anchor for this element component.
437+
* Gets the anchor for this element component. Use the setter to update the anchor.
438438
*
439-
* @type {Vec4 | number[]}
439+
* @type {Readonly<Vec4>}
440440
*/
441441
get anchor() {
442442
return this._anchor;
@@ -673,7 +673,7 @@ class ElementComponent extends Component {
673673
/**
674674
* Gets the array of layer IDs ({@link Layer#id}) to which this element belongs.
675675
*
676-
* @type {number[]}
676+
* @type {ReadonlyArray<number>}
677677
*/
678678
get layers() {
679679
return this._layers;
@@ -719,9 +719,10 @@ class ElementComponent extends Component {
719719
}
720720

721721
/**
722-
* Gets the distance from the left, bottom, right and top edges of the anchor.
722+
* Gets the distance from the left, bottom, right and top edges of the anchor. Use the setter to
723+
* update the margin.
723724
*
724-
* @type {Vec4}
725+
* @type {Readonly<Vec4>}
725726
*/
726727
get margin() {
727728
return this._margin;
@@ -783,9 +784,10 @@ class ElementComponent extends Component {
783784
}
784785

785786
/**
786-
* Gets the position of the pivot of the component relative to its anchor.
787+
* Gets the position of the pivot of the component relative to its anchor. Use the setter to
788+
* update the pivot.
787789
*
788-
* @type {Vec2 | number[]}
790+
* @type {Readonly<Vec2>}
789791
*/
790792
get pivot() {
791793
return this._pivot;
@@ -1272,9 +1274,9 @@ class ElementComponent extends Component {
12721274
}
12731275

12741276
/**
1275-
* Gets the color of the element.
1277+
* Gets the color of the element. Use the setter to update the color.
12761278
*
1277-
* @type {Color}
1279+
* @type {Readonly<Color>}
12781280
*/
12791281
get color() {
12801282
if (this._text) {
@@ -1820,9 +1822,10 @@ class ElementComponent extends Component {
18201822
}
18211823

18221824
/**
1823-
* Gets the region of the texture to use in order to render an image.
1825+
* Gets the region of the texture to use in order to render an image. Use the setter to update
1826+
* the region.
18241827
*
1825-
* @type {Vec4}
1828+
* @type {Readonly<Vec4>|null}
18261829
*/
18271830
get rect() {
18281831
if (this._image) {

‎src/framework/components/light/component.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -293,9 +293,9 @@ class LightComponent extends Component {
293293
}
294294

295295
/**
296-
* Gets the color of the light.
296+
* Gets the color of the light. Use the setter to update the color.
297297
*
298-
* @type {Color}
298+
* @type {Readonly<Color>}
299299
*/
300300
get color() {
301301
return this._light.getColor();
@@ -1177,7 +1177,7 @@ class LightComponent extends Component {
11771177
/**
11781178
* Gets the array of layer IDs ({@link Layer#id}) to which this light should belong.
11791179
*
1180-
* @type {number[]}
1180+
* @type {ReadonlyArray<number>}
11811181
*/
11821182
get layers() {
11831183
return this._layers;

‎src/framework/components/model/component.js‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -180,9 +180,10 @@ class ModelComponent extends Component {
180180
}
181181

182182
/**
183-
* Gets the array of mesh instances contained in the component's model.
183+
* Gets the array of mesh instances contained in the component's model. Use the setter to
184+
* replace the array; do not mutate the returned array.
184185
*
185-
* @type {MeshInstance[]|null}
186+
* @type {ReadonlyArray<MeshInstance>|null}
186187
*/
187188
get meshInstances() {
188189
if (!this._model) {
@@ -605,7 +606,7 @@ class ModelComponent extends Component {
605606
/**
606607
* Gets the array of layer IDs ({@link Layer#id}) to which the mesh instances belong.
607608
*
608-
* @type {number[]}
609+
* @type {ReadonlyArray<number>}
609610
*/
610611
get layers() {
611612
return this._layers;
@@ -775,7 +776,7 @@ class ModelComponent extends Component {
775776
/**
776777
* Gets the dictionary that holds material overrides for each mesh instance.
777778
*
778-
* @type {Object<string, number>}
779+
* @type {Readonly<Record<string, number>>}
779780
*/
780781
get mapping() {
781782
return this._mapping;

‎src/framework/components/particle-system/component.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1763,7 +1763,7 @@ class ParticleSystemComponent extends Component {
17631763
/**
17641764
* Gets the array of layer IDs ({@link Layer#id}) to which this particle system belongs.
17651765
*
1766-
* @type {number[]}
1766+
* @type {ReadonlyArray<number>}
17671767
*/
17681768
get layers() {
17691769
return this._layers;

‎src/framework/components/render/component.js‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -357,9 +357,10 @@ class RenderComponent extends Component {
357357
}
358358

359359
/**
360-
* Gets the array of meshInstances contained in the component.
360+
* Gets the array of meshInstances contained in the component. Use the setter to replace the
361+
* array; do not mutate the returned array.
361362
*
362-
* @type {MeshInstance[]}
363+
* @type {ReadonlyArray<MeshInstance>}
363364
*/
364365
get meshInstances() {
365366
return this._meshInstances;
@@ -547,7 +548,7 @@ class RenderComponent extends Component {
547548
/**
548549
* Gets the array of layer IDs ({@link Layer#id}) to which the mesh instances belong.
549550
*
550-
* @type {number[]}
551+
* @type {ReadonlyArray<number>}
551552
*/
552553
get layers() {
553554
return this._layers;

‎src/framework/components/rigid-body/component.js‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -237,9 +237,10 @@ class RigidBodyComponent extends Component {
237237
}
238238

239239
/**
240-
* Gets the scaling factor for angular movement of the body in each axis.
240+
* Gets the scaling factor for angular movement of the body in each axis. Use the setter to
241+
* update the physics body.
241242
*
242-
* @type {Vec3}
243+
* @type {Readonly<Vec3>}
243244
*/
244245
get angularFactor() {
245246
return this._angularFactor;
@@ -262,9 +263,10 @@ class RigidBodyComponent extends Component {
262263
}
263264

264265
/**
265-
* Gets the rotational speed of the body around each world axis.
266+
* Gets the rotational speed of the body around each world axis. Use the setter to update the
267+
* physics body.
266268
*
267-
* @type {Vec3}
269+
* @type {Readonly<Vec3>}
268270
*/
269271
get angularVelocity() {
270272
if (this._body && this._type === BODYTYPE_DYNAMIC) {
@@ -382,9 +384,10 @@ class RigidBodyComponent extends Component {
382384
}
383385

384386
/**
385-
* Gets the scaling factor for linear movement of the body in each axis.
387+
* Gets the scaling factor for linear movement of the body in each axis. Use the setter to
388+
* update the physics body.
386389
*
387-
* @type {Vec3}
390+
* @type {Readonly<Vec3>}
388391
*/
389392
get linearFactor() {
390393
return this._linearFactor;
@@ -407,9 +410,9 @@ class RigidBodyComponent extends Component {
407410
}
408411

409412
/**
410-
* Gets the speed of the body in a given direction.
413+
* Gets the speed of the body in a given direction. Use the setter to update the physics body.
411414
*
412-
* @type {Vec3}
415+
* @type {Readonly<Vec3>}
413416
*/
414417
get linearVelocity() {
415418
if (this._body && this._type === BODYTYPE_DYNAMIC) {

0 commit comments

Comments
 (0)