pma-locals 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,78 @@
+# pma-locals
+
+Modern TypeScript library for managing RedM ped spawning and animations.
+
+## Installation
+
+```bash
+npm install pma-locals
+# or
+pnpm add pma-locals
+```
+
+## Usage
+
+```typescript
+import { registerPed, processSpawning } from "pma-locals";
+import { Vector3, Delay } from "@nativewrappers/redm";
+
+// Register a ped with animation
+registerPed(
+	0x12345678, // model hash
+	new Vector3(-297.74, 791.1, 118.4), // spawn coords
+	180.0, // heading
+	50.0, // spawn distance (optional, default: 100.0)
+	{
+		dict: "amb_wander@world_human_smoke@male@male_a@idle_a",
+		anim: "idle_a",
+	}, // optional animation
+	undefined // optional prop data
+);
+
+// In your game loop
+setTick(async () => {
+	const playerPed = PlayerPedId();
+	if (!playerPed) return;
+
+	const coords = GetEntityCoords(playerPed, true, true);
+	const playerPos = new Vector3(coords[0], coords[1], coords[2]);
+
+	await processSpawning(playerPos);
+	await Delay(500);
+});
+```
+
+## API
+
+### `registerPed(modelName, coords, heading, spawnDistance?, animation?, propData?)`
+
+Register a ped to spawn when players approach.
+
+**Parameters:**
+
+-   `modelName` (number): Model hash
+-   `coords` (Vector3): Spawn coordinates
+-   `heading` (number): Ped heading direction
+-   `spawnDistance` (number): Distance threshold (default: 100.0)
+-   `animation` (Animation): Optional animation data
+-   `propData` (Props): Optional prop attachment
+
+### `processSpawning(playerPos: Vector3)`
+
+Update ped spawning based on player position. Call this in your game loop.
+
+### `cleanupPeds()`
+
+Delete all spawned peds (useful for resource cleanup).
+
+## Types
+
+Full TypeScript support with exported types:
+
+-   `PedConfig`
+-   `Animation`
+-   `Props`
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { Vector3 } from '@nativewrappers/redm';
+
+interface Animation {
+    dict: string;
+    anim: string;
+}
+interface Props {
+    model: string;
+    boneId: number;
+    offset: number[];
+    rotation: number[];
+}
+
+interface PedConfig {
+    modelName: number;
+    coords: Vector3;
+    heading: number;
+    spawnDistance: number;
+    animation?: Animation;
+    propData?: Props;
+}
+declare function registerPed(modelName: number, coords: Vector3, heading: number, spawnDistance?: number, animation?: Animation, propData?: Props): void;
+declare function processSpawning(playerPos: Vector3): Promise<void>;
+declare function cleanupPeds(): void;
+
+export { type Animation, type PedConfig, type Props, cleanupPeds, processSpawning, registerPed };

package/dist/index.js

@@ -0,0 +1,104 @@
+import { createPed, Model, AnimationFlags, IkControlFlags, createProp } from '@nativewrappers/redm';
+
+// client/ped-handler.ts
+var pedConfigs = [];
+var activePeds = /* @__PURE__ */ new Map();
+function registerPed(modelName, coords, heading, spawnDistance = 100, animation, propData) {
+  pedConfigs.push({
+    modelName,
+    coords,
+    heading,
+    spawnDistance,
+    animation,
+    propData
+  });
+}
+function getConfigKey(config) {
+  return `${config.coords.x}_${config.coords.y}_${config.coords.z}`;
+}
+function isPlayerNearCoords(playerPos, targetPos, distance) {
+  const dx = playerPos.x - targetPos.x;
+  const dy = playerPos.y - targetPos.y;
+  const dz = playerPos.z - targetPos.z;
+  return Math.sqrt(dx * dx + dy * dy + dz * dz) <= distance;
+}
+async function processSpawning(playerPos) {
+  for (const config of pedConfigs) {
+    const key = getConfigKey(config);
+    const isNear = isPlayerNearCoords(playerPos, config.coords, config.spawnDistance);
+    const isSpawned = activePeds.has(key);
+    if (isNear && !isSpawned) {
+      await spawnPed(config, key);
+    } else if (!isNear && isSpawned) {
+      despawnPed(key);
+    }
+  }
+}
+async function spawnPed(config, key) {
+  const ped = await createPed(new Model(config.modelName), config.coords, 0, false, true);
+  if (!ped) return;
+  SetRandomOutfitVariation(ped.Handle, true);
+  if (config.heading) {
+    ped.Heading = config.heading;
+  }
+  if (config.animation) {
+    await ped.Tasks.playAnimation(
+      config.animation.dict,
+      config.animation.anim,
+      8,
+      8,
+      -1,
+      1,
+      AnimationFlags.Looping,
+      IkControlFlags.UpperBody
+    );
+  }
+  let prop = null;
+  if (config.propData) {
+    prop = await createProp(new Model(config.propData.model), ped.Position, 0, true, true);
+    if (prop) {
+      AttachEntityToEntity(
+        prop.Handle,
+        ped.Handle,
+        config.propData.boneId,
+        config.propData.offset[0],
+        config.propData.offset[1],
+        config.propData.offset[2],
+        config.propData.rotation[0],
+        config.propData.rotation[1],
+        config.propData.rotation[2],
+        true,
+        false,
+        false,
+        true,
+        1,
+        true
+      );
+    }
+  }
+  activePeds.set(key, { ped, config, prop });
+}
+function despawnPed(key) {
+  const activePed = activePeds.get(key);
+  if (!activePed) return;
+  if (activePed.prop) {
+    activePed.prop.delete();
+  }
+  if (activePed.ped) {
+    activePed.ped.delete();
+  }
+  activePeds.delete(key);
+}
+function cleanupPeds() {
+  for (const [key, activePed] of activePeds) {
+    if (activePed.prop) {
+      activePed.prop.delete();
+    }
+    if (activePed.ped) {
+      activePed.ped.delete();
+    }
+    activePeds.delete(key);
+  }
+}
+
+export { cleanupPeds, processSpawning, registerPed };

package/package.json

@@ -1,25 +1,44 @@
 {
   "name": "pma-locals",
-  "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
+  "version": "1.0.2",
+  "description": "RedM ped spawning and management library with TypeScript support",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "type": "module",
-  "scripts": {
-    "watch": "node ./scripts/dev.js",
-    "build": "node ./scripts/prod.js"
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
-  "keywords": [],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "redm",
+    "fivem",
+    "ped",
+    "npc",
+    "typescript"
+  ],
   "author": "",
   "license": "ISC",
-  "packageManager": "pnpm@10.15.0",
-  "dependencies": {
-    "@nativewrappers/redm": "^0.0.141",
-    "@nativewrappers/server": "^0.0.141",
-    "esbuild": "^0.27.2"
+  "peerDependencies": {
+    "@nativewrappers/redm": "^0.0.141"
   },
   "devDependencies": {
     "@citizenfx/client": "2.0.23683-1",
     "@citizenfx/server": "2.0.23683-1",
-    "@types/node": "^25.0.3"
+    "@nativewrappers/redm": "^0.0.141",
+    "@types/node": "^25.0.3",
+    "esbuild": "^0.27.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "watch": "node ./scripts/dev.js",
+    "build": "node ./scripts/prod.js",
+    "build:package": "tsup"
   }
 }

package/client/main.ts

@@ -1,33 +0,0 @@
-import { Delay, Vector3 } from "@nativewrappers/redm";
-import { cleanupPeds, processSpawning } from "./ped-handler";
-
-// Example: Register peds with their spawn coordinates
-// registerPed(
-// 	0x12345678, // model hash
-// 	new Vector3(-297.74, 791.1, 118.4), // spawn coords
-// 	180.0, // heading
-// 	50.0, // spawn distance
-// 	{ dict: "amb_wander@world_human_smoke@male@male_a@idle_a", anim: "idle_a" }, // optional animation
-// 	undefined // optional prop data
-// );
-
-setTick(async () => {
-	const playerPed = PlayerPedId();
-	if (!playerPed) {
-		await Delay(500);
-		return;
-	}
-
-	const coords = GetEntityCoords(playerPed, true, true);
-	const playerPos = new Vector3(coords[0], coords[1], coords[2]);
-
-	await processSpawning(playerPos);
-
-	await Delay(500);
-});
-
-on("onResourceStop", (resourceName: string) => {
-	if (resourceName !== GetCurrentResourceName()) return;
-	console.log(`Restarting ${resourceName}`);
-	cleanupPeds();
-});

package/client/ped-handler.ts

@@ -1,151 +0,0 @@
-import { Animation, Props } from "$types/index";
-import {
-    AnimationFlags,
-    createPed,
-    createProp,
-    IkControlFlags,
-    Model,
-    Prop,
-    Vector3,
-} from "@nativewrappers/redm";
-
-export interface PedConfig {
-    modelName: number;
-    coords: Vector3;
-    heading: number;
-    spawnDistance: number;
-    animation?: Animation;
-    propData?: Props;
-}
-
-interface ActivePedData {
-    ped: any;
-    config: PedConfig;
-    prop: Prop | null;
-}
-
-// Module-level state
-const pedConfigs: PedConfig[] = [];
-const activePeds: Map<string, ActivePedData> = new Map();
-
-export function registerPed(
-    modelName: number,
-    coords: Vector3,
-    heading: number,
-    spawnDistance: number = 100.0,
-    animation?: Animation,
-    propData?: Props
-) {
-    pedConfigs.push({
-        modelName,
-        coords,
-        heading,
-        spawnDistance,
-        animation,
-        propData,
-    });
-}
-
-function getConfigKey(config: PedConfig): string {
-    return `${config.coords.x}_${config.coords.y}_${config.coords.z}`;
-}
-
-function isPlayerNearCoords(playerPos: Vector3, targetPos: Vector3, distance: number): boolean {
-    const dx = playerPos.x - targetPos.x;
-    const dy = playerPos.y - targetPos.y;
-    const dz = playerPos.z - targetPos.z;
-    return Math.sqrt(dx * dx + dy * dy + dz * dz) <= distance;
-}
-
-export async function processSpawning(playerPos: Vector3) {
-    for (const config of pedConfigs) {
-        const key = getConfigKey(config);
-        const isNear = isPlayerNearCoords(playerPos, config.coords, config.spawnDistance);
-        const isSpawned = activePeds.has(key);
-
-        if (isNear && !isSpawned) {
-            // Player is within range and ped is not spawned -> spawn it
-            await spawnPed(config, key);
-        } else if (!isNear && isSpawned) {
-            // Player is outside range and ped is spawned -> delete it
-            despawnPed(key);
-        }
-    }
-}
-
-async function spawnPed(config: PedConfig, key: string) {
-    const ped = await createPed(new Model(config.modelName), config.coords, 0.0, false, true);
-    if (!ped) return;
-    SetRandomOutfitVariation(ped.Handle, true);
-    if (config.heading) {
-        ped.Heading = config.heading;
-    }
-
-    if (config.animation) {
-        await ped.Tasks.playAnimation(
-            config.animation.dict,
-            config.animation.anim,
-            8.0,
-            8.0,
-            -1,
-            1,
-            AnimationFlags.Looping,
-            IkControlFlags.UpperBody
-        );
-    }
-
-    let prop: Prop | null = null;
-    if (config.propData) {
-        prop = await createProp(new Model(config.propData.model), ped.Position, 0, true, true);
-        if (prop) {
-            AttachEntityToEntity(
-                prop.Handle,
-                ped.Handle,
-                config.propData.boneId,
-                config.propData.offset[0],
-                config.propData.offset[1],
-                config.propData.offset[2],
-                config.propData.rotation[0],
-                config.propData.rotation[1],
-                config.propData.rotation[2],
-                true,
-                false,
-                false,
-                true,
-                1,
-                true
-            );
-        }
-    }
-
-    activePeds.set(key, { ped, config, prop });
-}
-
-function despawnPed(key: string) {
-    const activePed = activePeds.get(key);
-    if (!activePed) return;
-
-    if (activePed.prop) {
-        activePed.prop.delete();
-    }
-
-    if (activePed.ped) {
-        activePed.ped.delete();
-    }
-
-    activePeds.delete(key);
-}
-
-export function cleanupPeds() {
-    for (const [key, activePed] of activePeds) {
-        if (activePed.prop) {
-            activePed.prop.delete();
-        }
-
-        if (activePed.ped) {
-            activePed.ped.delete();
-        }
-
-        activePeds.delete(key);
-    }
-}

package/client/tsconfig.json

@@ -1,29 +0,0 @@
-{
-    "extends": "../tsconfig.json",
-    "compilerOptions": {
-        "baseUrl": ".",
-        "composite": true,
-        "types": [
-            "@types/node",
-            "@citizenfx/client",
-            "@nativewrappers/redm",
-            "../definitions/index.ts"
-        ],
-        "paths": {
-            "$types/*": [
-                "../types/*",
-                "../definitions/index.ts"
-            ],
-            "$shared/*": [
-                "../shared/*"
-            ]
-        },
-        "resolveJsonModule": true,
-        "esModuleInterop": true
-    },
-    "include": [
-        "./",
-        "../types/*",
-        "../shared/*",
-    ]
-}

package/definitions/Citizen.d.ts

@@ -1,205 +0,0 @@
-/* eslint-disable */
-
-interface IntPtrInitialized {}
-interface FloatPtrInitialized {}
-interface IntPtr {}
-interface FloatPtr {}
-interface VectorPtr {}
-interface ReturnResultAnyway {}
-interface ResultAsInteger {}
-interface ResultAsFloat {}
-interface ResultAsString {}
-interface ResultAsVector {}
-interface ResultAsLong {}
-interface ResultAsObject {}
-
-type InputArgument =
-  | string
-  | number
-  | IntPtrInitialized
-  | FloatPtrInitialized
-  | IntPtr
-  | FloatPtr
-  | VectorPtr
-  | ReturnResultAnyway
-  | ResultAsInteger
-  | ResultAsFloat
-  | ResultAsString
-  | ResultAsVector
-  | ResultAsLong
-  | ResultAsObject;
-
-interface StateBagInterface {
-  [key: string]: any;
-  set(key: string, value: any, replicated: boolean): void;
-}
-
-interface EntityInterface {
-  state: StateBagInterface;
-}
-
-interface CitizenInterface {
-  trace(...args: string[]): void;
-  setTickFunction(callback: Function): void;
-  setEventFunction(callback: Function): void;
-
-  setCallRefFunction(callback: Function): void;
-  setDeleteRefFunction(callback: Function): void;
-  setDuplicateRefFunction(callback: Function): void;
-  canonicalizeRef(ref: number): string;
-  invokeFunctionReference(ref: string, args: Uint8Array): Uint8Array;
-
-  getTickCount(): number;
-  invokeNative<T = void>(hash: string, ...args: InputArgument[]): T;
-  invokeNativeByHash<T = void>(
-    hash1: number,
-    hash2: number,
-    ...args: InputArgument[]
-  ): T;
-  startProfiling(name?: string): void;
-  stopProfiling(name?: string): {};
-
-  pointerValueIntInitialized(): IntPtrInitialized;
-  pointerValueFloatInitialized(): FloatPtrInitialized;
-  pointerValueInt(): IntPtr;
-  pointerValueFloat(): FloatPtr;
-  pointerValueVector(): VectorPtr;
-  returnResultAnyway(): ReturnResultAnyway;
-  resultAsInteger(): ResultAsInteger;
-  resultAsFloat(): ResultAsFloat;
-  resultAsString(): ResultAsString;
-  resultAsVector(): ResultAsVector;
-  resultAsLong(): ResultAsLong;
-  resultAsObject(): ResultAsObject;
-
-  makeRefFunction(refFunction: Function): string;
-}
-
-interface CitizenTimer {
-  ref(): CitizenTimer;
-  unref(): CitizenTimer;
-  hasRef(): boolean;
-  refresh(): CitizenTimer;
-  [Symbol.toPrimitive](): number;
-}
-
-type CitizenImmediate = Omit<CitizenTimer, "refresh">;
-
-declare let Citizen: CitizenInterface;
-
-declare function addRawEventListener(
-  eventName: string,
-  callback: Function,
-): void;
-
-declare function addEventListener(
-  eventName: string,
-  callback: Function,
-  netSafe?: boolean,
-): void;
-declare function on(eventName: string, callback: Function): void;
-declare function AddEventHandler(eventName: string, callback: Function): void;
-
-declare function addNetEventListener(
-  eventName: string,
-  callback: Function,
-): void;
-declare function onNet(eventName: string, callback: Function): void;
-
-declare function emit(eventName: string, ...args: any[]): void;
-declare function TriggerEvent(eventName: string, ...args: any[]): void;
-
-declare function emitNet(eventName: string, ...args: any[]): void;
-declare function TriggerServerEvent(eventName: string, ...args: any[]): void;
-declare function TriggerLatentServerEvent(
-  eventName: string,
-  bps: number,
-  ...args: any[]
-): void;
-
-declare function getPlayerIdentifiers(player: number | string): string[];
-declare function getPlayerTokens(player: number | string): string[];
-declare function getPlayers(): string[];
-
-declare function SendNUIMessage(data: any): void;
-
-declare function emitNet(
-  eventName: string,
-  target: number | string,
-  ...args: any[]
-): void;
-declare function TriggerClientEvent(
-  eventName: string,
-  target: number | string,
-  ...args: any[]
-): void;
-declare function TriggerLatentClientEvent(
-  eventName: string,
-  target: number | string,
-  bps: number,
-  ...args: any[]
-): void;
-
-declare function removeEventListener(
-  eventName: string,
-  callback: Function,
-): void;
-
-declare function setTimeout<T extends any[]>(
-  callback: (...args: T) => void,
-  ms?: number,
-  ...args: T
-): CitizenTimer;
-declare function clearTimeout(timeout: CitizenTimer): void;
-
-declare function setInterval<T extends any[]>(
-  callback: (...args: T) => void,
-  ms?: number,
-  ...args: T
-): CitizenTimer;
-declare function clearInterval(interval: CitizenTimer): void;
-
-declare function setImmediate<T extends any[]>(
-  callback: (...args: T) => void,
-  ...args: T
-): CitizenImmediate;
-declare function clearImmediate(immediate: CitizenImmediate): void;
-
-declare function setTick(callback: Function): number;
-declare function clearTick(callback: number): void;
-
-declare function NewStateBag(name: string): StateBagInterface;
-declare function Entity(entity: number): EntityInterface;
-declare let GlobalState: StateBagInterface;
-declare function Player(entity: number | string): EntityInterface;
-declare let LocalPlayer: EntityInterface;
-
-declare let exports: any;
-
-declare let source: number;
-
-// Commented methods are not implemented yet
-interface Console {
-  assert(condition?: boolean, ...data: any[]): void;
-  // clear(): void;
-  count(label?: string): void;
-  countReset(label?: string): void;
-  debug(...data: any[]): void;
-  dir(item?: any, options?: any): void;
-  // dirxml(...data: any[]): void;
-  error(...data: any[]): void;
-  // group(...data: any[]): void;
-  // groupCollapsed(...data: any[]): void;
-  // groupEnd(): void;
-  info(...data: any[]): void;
-  log(...data: any[]): void;
-  // table(tabularData?: any, properties?: string[]): void;
-  time(label?: string): void;
-  timeEnd(label?: string): void;
-  // timeLog(label?: string, ...data: any[]): void;
-  // timeStamp(label?: string): void;
-  trace(...data: any[]): void;
-  warn(...data: any[]): void;
-}
-
-declare let console: Console;

package/definitions/index.d.ts

@@ -1,4 +0,0 @@
-/// <reference path="./Citizen.d.ts" />
-/// <reference path="./redm.d.ts" />
-/// <reference path="./json.d.ts" />
-/// <reference path="../web/src/png.d.ts" />

package/definitions/json.d.ts

@@ -1,4 +0,0 @@
-declare module "*.json" {
-    const value: any;
-    export default value;
-  }