Merge pull request #91 from ollymonger/feat/add-client-types-for-entity-overlays

chore: Add clientside graphics typings for entity overlays

Author: shr0x

packages/client/game/graphics.d.ts

@@ -1291,6 +1291,184 @@ declare interface GameGraphics extends GameGraphicsLegacy {
 	registerTextFontId(fontname: string): number;
 	setNumberPlateTexture(txDict: string, txName: string, txDictNormal: string, txNameNorma: string): void;
 	setParticleFxBloodScale(scale: number): void;
+
+	/**
+	 * Returns a batch object for using overlays on entities.
+	 * @param overlayParams 
+	 * 
+	 * @example
+	 *	let overlayParams = {
+	 *			enableDepth: true,
+	 *			deleteWhenUnused: false,
+	 *			keepNonBlurred: true,
+	 *			processAttachments: true,
+	 *			fill: { enable: false, color: 0xFFFFFFFF },
+	 *			noise: { enable: false, size: 0.0, speed: 0.0, intensity: 0.0 },
+	 *			outline: { enable: true, color: 0xFF9000FF, width: 5.0, blurRadius: 1.0, blurIntensity: 1.0 },
+	 *			wireframe: { enable: false }
+	 *	};
+	 *
+   * 	mp.game.graphics.setEntityOverlayPassEnabled(true);
+	 *
+	 *	let batch = mp.game.graphics.createEntityOverlayBatch(overlayParams);
+ 	 *
+	 *	mp.events.add('render', () => {
+	 *			batch.addThisFrame(mp.players.local);
+	 *	});
+	 */
+	createEntityOverlayBatch(overlayParams: {
+    enableDepth: boolean,
+    deleteWhenUnused: boolean,
+    keepNonBlurred: boolean,
+    processAttachments: boolean,
+    fill: { enable: boolean, color: number },
+    noise: { enable: boolean, size: number, speed: number, intensity: number },
+    outline: { enable: boolean, color: number, width: number, blurRadius: number, blurIntensity: number },
+    wireframe: { enable: boolean }
+	}): {
+
+		/**
+		 * Update an existing entity overlay batch created with createEntityOverlayBatch
+		 * @param overlayParams 
+		 * 
+		 * @example
+		 * 
+		 * //update its fill color
+		 * let overlayParams =  { ... }
+		 * let batch = mp.game.graphics.createEntityOverlayBatch(overlayParams);
+		 * 
+		 * mp.events.add('updatebatchcolor', () => {
+		 *		overlayParams.fill.color = 0x00AA00FF;
+		 *		batch.update(overlayParams);
+		 * });
+		 * 
+		 */
+		update(overlayParams: {
+			enableDepth: boolean,
+			deleteWhenUnused: boolean,
+			keepNonBlurred: boolean,
+			processAttachments: boolean,
+			fill: { enable: boolean, color: number },
+			noise: { enable: boolean, size: number, speed: number, intensity: number },
+			outline: { enable: boolean, color: number, width: number, blurRadius: number, blurIntensity: number },
+			wireframe: { enable: boolean }
+		}): void,
+
+		/**
+		 * This method will destroy an entity overlay batch.
+		 * @example
+		  * // Enable entity overlay batch
+			* mp.game.graphics.setEntityOverlayPassEnabled(true);
+			* 
+			* // Create new entity overlay batch with specified parameters
+			* const overlayParams = { ... };
+			* let batch = mp.game.graphics.createEntityOverlayBatch(overlayParams);
+			* 
+			* // Add a vehicle to the overlay batch once the player enters it
+			* mp.events.add('playerEnterVehicle', (vehicle) => {
+			*     batch.add(vehicle);
+			* });
+			* 
+			* // Add an event to destroy the created batch
+			* mp.events.add("client_batch_destroy", () => {
+			*     batch.destroy();
+			*     mp.console.logInfo(`Entity overlay batch was destroyed successfully.`);
+			* });
+		 */
+		destroy(): void,
+
+		/**
+		 * This property will return whether an entity overlay is valid or not.
+		 * Note: This property is readonly.
+		 * @returns boolean
+		 */
+		valid: boolean,
+
+		/**
+		 * This method will add an entity to overlay batch.
+		 * @param entity 
+		 * 
+		 * @example
+		 * //Enable entity overlay batch.
+		 *	mp.game.graphics.setEntityOverlayPassEnabled(true);
+		 *	//Create a new entity overlay batch.
+		 *	let batch = mp.game.graphics.createEntityOverlayBatch(overlayParams);
+
+		 *	//Add a vehicle to overlay batch once the player enters in them.
+		 *	mp.events.add('playerEnterVehicle', (vehicle) => {
+		 *		batch.add(vehicle);
+		 *	});
+		 */
+		add(entity: number): void,
+
+		/**
+		 * This method will remove an entity from overlay batch.
+		 * @param entity 
+		 * 
+		 * @example
+		 * //Enable entity overlay batch
+		 *	mp.game.graphics.setEntityOverlayPassEnabled(true);
+
+		 *	//Create new entity overlay batch
+		 *	let batch = mp.game.graphics.createEntityOverlayBatch(overlayParams);
+
+		 *	//Add a vehicle to overlay batch once the player enters in them.
+		 *	mp.events.add('playerEnterVehicle', (vehicle) => {
+		 *		batch.add(vehicle);
+		 *	});
+
+		 *	//Remove vehicle from batch once the player leaves them.
+		 *	mp.events.add('playerLeaveVehicle', (vehicle) => {
+		 *		batch.remove(vehicle);
+		 *	})
+		 */
+		remove(entity: number): void,
+
+		/**
+		 * This method will add an entity to overlay batch only this frame.
+		 * @param entity
+		 * //Enable entity overlay batch
+		 * mp.game.graphics.setEntityOverlayPassEnabled(true);
+
+     * //Create new entity overlay batch
+     * let batch = mp.game.graphics.createEntityOverlayBatch(overlayParams);
+
+		 * //Add streamed vehicles to overlay batch.
+		 * mp.events.add('render', () => {
+     * 	mp.vehicles.forEachInStreamRange((vehicle) => {
+      		batch.addThisFrame(vehicle);
+     * 	})
+		 * });
+		 */
+		addThisFrame(entity: number): void,
+
+		/**
+		 * This method will remove an entity from overlay batch only this frame.
+		 * @param entity 
+		 * 
+		 * @example
+		 *	let batch = mp.game.graphics.createEntityOverlayBatch(overlayParams);
+
+		 *	//Remove vehicle from batch once the player leaves them.
+		 *	mp.events.add('playerLeaveVehicle', (vehicle) => {
+		 *		batch.remove(vehicle);
+		 *	})
+		 */
+		removeThisFrame(entity: number): void,
+	}
+
+	/**
+	 * This method will enable or disable entity overlay feature.
+	 * @param enable 
+	 * 
+	 * @example
+	 * //enable entity overlay
+	 * mp.game.graphics.setEntityOverlayPassEnabled(true);
+	 * 
+	 * //disable entity overlay
+	 * mp.game.graphics.setEntityOverlayPassEnabled(false);
+	 */
+	setEntityOverlayPassEnabled(enable: boolean): void,
 }
 
 declare interface GameGraphicsMp extends GameGraphics { }