NeedsService

Defined in: src/modules/core/needs/needs.service.ts:76

Needs service handling hunger, thirst, health, and armor.

Uses two observables for automatic synchronization:

• needsState: Server-owned, contains hunger/thirst, decays over time
• vitalsState: Client-owned, contains health/armor from ped

HUD subscribes directly to both observables - no intermediate state needed.

Per-Player Observable Architecture

The needsState class field serves different purposes per runtime:

Runtime	Purpose
Server	Template only - actual per-player observables are created
	in hydratePlayer() and stored in playerObservables
Client	The observable that receives updates for this player
Web	Stub that receives values via the web subscription system

On the server, each player gets their own ServerOwnedObservable instance created with their persisted data. This allows:

• Different initial values per player (loaded from database)
• Independent subscription management per player
• Clean disposal when players disconnect

The class field's observable on server is essentially unused (a side effect of TypeScript field initialization) but is harmless since perPlayer: true observables skip global registration.

Constructors

Constructor

new NeedsService(): NeedsService;

Returns

NeedsService

Properties

Property	Type	Description	Defined in
needsState	ServerOwnedObservable<{ hunger: number; thirst: number; }>	Server-owned observable for needs (hunger, thirst). Server writes via decay loop, client/web read for display.	src/modules/core/needs/needs.service.ts:90
vitalsState	ClientOwnedObservable<{ armor: number; health: number; }>	Client-owned observable for vitals (health, armor). Client writes from ped sampling, server/web read.	src/modules/core/needs/needs.service.ts:100

Methods

applyFeedEffect()

applyFeedEffect(ctx: EventContext<[{
  amount: number;
  restoreHunger: boolean;
  restoreThirst: boolean;
}]>): Promise<void>;

Defined in: src/modules/core/needs/needs.service.ts:171

Apply a feed effect to restore hunger/thirst. Called by the inventory system when a consumable with "effect/feed" is used.

Parameters

Parameter	Type
ctx	EventContext<[{ amount: number; restoreHunger: boolean; restoreThirst: boolean; }]>

Returns

Promise<void>

---

applyHealEffect()

applyHealEffect(ctx: EventContext<[{
  healthAmount: number;
}]>): Promise<void>;

Defined in: src/modules/core/needs/needs.service.ts:201

Apply a heal effect to restore health. Called by the inventory system when a consumable with "effect/heal" is used. Note: This only stores the intent - actual health modification happens client-side via the vitals observable sync.

Parameters

Parameter	Type
ctx	EventContext<[{ healthAmount: number; }]>

Returns

Promise<void>

---

applyHealOnClient()

applyHealOnClient(ctx: EventContext<[number]>): Promise<void>;

Defined in: src/modules/core/needs/needs.service.ts:219

Apply heal on the client side by modifying ped health. Called from server when a heal effect is triggered.

Parameters

Parameter	Type
ctx	EventContext<[number]>

Returns

Promise<void>

---

cleanupClientSide()

cleanupClientSide(): void;

Defined in: src/modules/core/needs/needs.service.ts:387

Clean up client-side resources.

Returns

void

---

cleanupServerSide()

cleanupServerSide(): void;

Defined in: src/modules/core/needs/needs.service.ts:303

Clean up server-side resources.

Returns

void

---

getPersistedVitals()

getPersistedVitals(ctx: EventContext<[]>): Promise<
  | {
  armor: number;
  health: number;
}
| null>;

Defined in: src/modules/core/needs/needs.service.ts:141

Client requests persisted vitals after hydration. Returns vitals that were stored during the previous session, if any. The client should call this once during initialization to restore vitals.

Parameters

Parameter	Type
ctx	EventContext<[]>

Returns

Promise< | { armor: number; health: number; } | null>

---

initClientSide()

initClientSide(): void;

Defined in: src/modules/core/needs/needs.service.ts:332

Initialize client-side vitals sampling.

Returns

void

---

initServerSide()

initServerSide(): void;

Defined in: src/modules/core/needs/needs.service.ts:251

Initialize server-side needs decay and player tracking.

Returns

void

---

requestSync()

requestSync(ctx: EventContext<[]>): Promise<void>;

Defined in: src/modules/core/needs/needs.service.ts:122

Client requests initial sync after it's ready. This ensures the client's onNet listener is registered before receiving data. Called after character selection completes and player spawns.

Parameters

Parameter	Type
ctx	EventContext<[]>

Returns

Promise<void>