@warpfx/client 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -35,6 +35,43 @@ interface SyncRef<T = any> {
     /** React to state changes. Returns an unsubscribe function. */
     watch(handler: (newState: T, oldState: T) => void): () => void;
 }
+/** Entity type for proximity queries. */
+type NearbyEntityType = "player" | "vehicle" | "ped" | "object";
+/** An entity within proximity range. */
+interface NearbyEntity {
+    /** FiveM entity handle. */
+    id: number;
+    /** Entity type. */
+    type: NearbyEntityType;
+    /** World coordinates. */
+    coords: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Distance from the local player. */
+    distance: number;
+    /** FiveM server ID — only present for `player` type. */
+    serverId?: number;
+}
+/** Options for the `nearby()` proximity query. */
+interface NearbyOptions {
+    /** Maximum distance to include entities. */
+    range: number;
+    /** Entity types to track. Defaults to all types. */
+    types?: NearbyEntityType[];
+    /** Milliseconds between proximity checks. Defaults to 500. */
+    interval?: number;
+}
+/** Reactive handle to nearby entities. SyncRef-compatible (works with `watch()`). */
+interface NearbyRef {
+    /** Current nearby entities (latest check result). */
+    readonly value: NearbyEntity[];
+    /** React to changes in the nearby set. Returns an unsubscribe function. */
+    watch(handler: (current: NearbyEntity[], previous: NearbyEntity[]) => void): () => void;
+    /** Stop tracking and clean up this consumer. */
+    destroy(): void;
+}
 /** Action error received from the server. */
 interface ActionError {
     action: string;
@@ -100,6 +137,27 @@ declare function watch<T extends readonly SyncRef[]>(refs: readonly [...T], hand
 }, oldValues: {
     [K in keyof T]: T[K] extends SyncRef<infer V> ? V : never;
 }) => void): () => void;
+/**
+ * Track nearby entities with a shared, optimized proximity tick.
+ *
+ * All `nearby()` consumers share a single game-thread loop — instead of
+ * N modules each running their own `GetEntityCoords` tick. Watchers fire
+ * when entities enter or leave the range.
+ *
+ * The returned ref is SyncRef-compatible and works with `watch()`.
+ *
+ * @example
+ * const entities = nearby({ range: 50, types: ['player', 'vehicle'] });
+ *
+ * entities.watch((current, previous) => {
+ *   console.log(`${current.length} entities nearby`);
+ * });
+ *
+ * const closest = entities.value
+ *   .filter(e => e.type === 'player')
+ *   .sort((a, b) => a.distance - b.distance)[0];
+ */
+declare function nearby(options: NearbyOptions): NearbyRef;
 /**
  * Register a global error handler for all action errors.
  * Returns an unsubscribe function.
@@ -145,4 +203,4 @@ declare function onNUI<T = any>(name: string, handler: (data: T) => any): void;
  */
 declare function registerKeybind(name: string, options: KeybindOptions): void;
 
-export { type ActionError, type ClientEventBus, type KeybindOptions, type ShowNUIOptions, type SyncRef, action, call, getEvents, hideNUI, isReady, onError, onNUI, onReady, registerKeybind, sendNUI, setNUIFocus, showNUI, sync, watch };
+export { type ActionError, type ClientEventBus, type KeybindOptions, type NearbyEntity, type NearbyEntityType, type NearbyOptions, type NearbyRef, type ShowNUIOptions, type SyncRef, action, call, getEvents, hideNUI, isReady, nearby, onError, onNUI, onReady, registerKeybind, sendNUI, setNUIFocus, showNUI, sync, watch };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   getEvents: () => getEvents,
   hideNUI: () => hideNUI,
   isReady: () => isReady,
+  nearby: () => nearby,
   onError: () => onError,
   onNUI: () => onNUI,
   onReady: () => onReady,
@@ -66,6 +67,9 @@ function watch(refs, handler) {
   );
   return () => unsubs.forEach((fn) => fn());
 }
+function nearby(options) {
+  return warp().nearby(options);
+}
 function onError(handler) {
   return warp().onError(handler);
 }
@@ -103,6 +107,7 @@ function registerKeybind(name, options) {
   getEvents,
   hideNUI,
   isReady,
+  nearby,
   onError,
   onNUI,
   onReady,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpfx/client",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Warp Framework SDK for client-side FiveM module development",
   "keywords": [
     "client",