feat: useWeapon, useState, some sync stuff, saving stuff, etc.

docs/api/server/controllers/blip.md

@@ -17,7 +17,7 @@ import { BlipColor } from '@Shared/types/blip.js';
 const Rebar = useRebar();
 
 // Create a global blip
-const blip = Rebar.controllers.useBlipGlobal(player, {
+const blip = Rebar.controllers.useBlipGlobal({
     pos: SpawnPos,
     color: BlipColor.BLUE,
     sprite: 57,

docs/api/server/document/document-character.md

@@ -8,6 +8,20 @@ It automatically saves data to the MongoDB database when any `set` function is u
 
 You should bind character data after fetching call characters owned by an account.
 
+When you bind character data to a player the following is synchronized:
+
+-   Position
+-   Rotation
+-   Clothing
+-   Appearance
+-   Model
+-   Skin
+-   Weapons
+-   Weapon Ammo
+-   Health
+-   Armor
+-   Dimension
+
 ```ts
 import { useRebar } from '@Server/index.js';
 

docs/api/server/document/document-vehicle.md

@@ -8,6 +8,18 @@ It automatically saves data to the MongoDB database when any `set` function is u
 
 You should bind character data after fetching call characters owned by an account.
 
+When you bind vehicle data to a vehicle the following is synchronized:
+
+-   Position
+-   Rotation
+-   Model
+-   Mods
+-   Health
+-   Windows
+-   Wheels
+-   Extras
+-   Dimension
+
 ```ts
 import { useRebar } from '@Server/index.js';
 

docs/api/server/player/player-appearance.md

@@ -45,5 +45,5 @@ appearance.setModel(true);
 appearance.setTattoos([{ collection: 'mpairraces_overlays', overlay: 'MP_Airraces_Tattoo_000_M' }]);
 
 // Called automatically, but resynchronizes freeroam player appearance
-appearance.update();
+appearance.sync();
 ```

docs/api/server/player/player-clothing.md

@@ -56,5 +56,5 @@ clothing.setClothingComponent('mask', alt.hash('some_dlc'), 5, 0, 0);
 clothing.setPropComponent('glasses', alt.hash('some_dlc'), 5, 0);
 
 // Forces character clothing to update, and rerenders everything
-clothing.update();
+clothing.sync();
 ```

docs/api/server/player/player-state.md

@@ -0,0 +1,17 @@
+# Weapon
+
+Used to synchronize or apply weapons to a player.
+
+```ts
+import { useRebar } from '@Server/index.js';
+
+const Rebar = useRebar();
+
+const playerState = Rebar.player.useState(somePlayer);
+
+// Use character document for weapons
+playerState.sync();
+
+// Override and apply some state to a player
+playerWeapons.apply({ pos: alt.Vector3.zero });
+```

docs/api/server/player/player-weapon.md

@@ -0,0 +1,44 @@
+# Weapon
+
+Used to synchronize or apply weapons to a player.
+
+```ts
+import { useRebar } from '@Server/index.js';
+
+const Rebar = useRebar();
+
+const playerWeapons = Rebar.player.useWeapon(somePlayer);
+
+// Use character document for weapons
+playerWeapons.sync();
+
+// Save weapons & ammo
+await playerWeapons.save();
+
+// Save just ammo
+await playerWeapons.saveAmmo();
+
+// Add a weapon, and save to the database, and re-apply weapons
+await playerWeapons.add('WEAPON_MINIGUN', 100);
+
+// Add ammo for specific gun
+await playerWeapons.addAmmo('WEAPON_MINIGUN', 100);
+
+// Clear all weapons & ammo
+await playerWeapons.clear();
+
+// Remove a weapon and all ammo for the weapon
+await playerWeapons.clearWeapon('WEAPON_MINIGUN');
+
+// Override and apply weapons to a player
+const weapons = [
+    { hash: alt.hash('WEAPON_MINIGUN'), components: [], tintIndex: 0 },
+    { hash: alt.hash('WEAPON_RPG'), components: [], tintIndex: 0 },
+];
+const ammo = {
+    [alt.hash('WEAPON_MINIGUN')]: 999,
+    [alt.hash('WEAPON_RPG')]: 5,
+};
+
+playerWeapons.apply(weapons, ammo);
+```

docs/api/server/vehicle/vehicle-use.md

@@ -0,0 +1,27 @@
+# useVehicle
+
+Used to create a new vehicle document, repair vehicles, apply vehicle documents, etc.
+
+```ts
+import { useRebar } from '@Server/index.js';
+
+const Rebar = useRebar();
+
+// Used to apply mods, health, etc. to a vehicle if it has a document bound
+Rebar.vehicle.useVehicle(vehicle).sync();
+
+// Use a document template to any given vehicle, does not save data
+Rebar.vehicle.useVehicle(vehicle).apply({ pos: new alt.Vector3(0, 0, 0) });
+
+// Save all current damage, position, rotation etc.
+// This does not create a new document for the given vehicle
+Rebar.vehicle.useVehicle(vehicle).save();
+
+// Correctly repairs the vehicle and returns the new vehicle instance
+// Players will be removed from the vehicle on repair
+await Rebar.vehicle.useVehicle(vehicle).repair();
+
+// Creating a vehicle and assigning it to a character id, or some other identifier
+const newVehicle = new alt.Vehicle('infernus', alt.Vector3.zero, alt.Vector3.zero);
+const document = await Rebar.vehicle.useVehicle(newVehicle).create(someCharacterIdOrSomethingElse);
+```

docs/changelog.md

@@ -4,6 +4,44 @@ order: -1000
 
 # Changelog
 
+## Version 6
+
+### Code Changes
+
+-   Added `vehicle` synchronization when a vehicle document is bound to the vehicle
+-   Added `useVehicle` function for synchronizing vehicle data, applying data, repairing, and creating new vehicle documents
+    -   Synchronizes damage (not appearance)
+    -   Synchronizes position, and rotation
+    -   Synchronizes window damage
+    -   Synchronizes tire damage
+    -   Synchronizes dirt levels
+    -   Synchronizes mods
+-   Added `character` synchronization when a character document is bound to the player
+    -   Synchronizes appearance, and clothing
+    -   Synchronizes weapons, and ammo
+    -   Synchronizes position, and rotation
+    -   Synchronizes health, and armor
+    -   Synchronizes death state
+-   Added ways to disable auto-sync for `vehicle` and `character` documents in the `binding` functions
+-   Added `onKeyUp` to the `Webview Events` functionality, allowing an easy way to listen for keybinds
+-   Added `playFrontendSound` to `useAudio` composable in the webview
+-   Added `useWeapon` to player pathway. Allows for synchronizing weapons, and ammo for database
+-   Added ability for commands to be `async`
+-   Separated logic for appyling data on `appearance` and `clothing` so overrides are possible
+-   Changed all `update()` functions to `sync` and added backwards compatible `update` function
+-   Split `Character` into `BaseCharacter` and `Character`, nothing changed externally
+
+### Docs Changes
+
+-   Updated `blip` controller docs for typo
+-   Added `useVehicle` documentation
+-   Updated documentation for `useCharacterBinder` that will allow ignoring auto-sync on binding
+-   Updated documentation for `useVehicleBinder` that will allow ignoring auto-sync on binding
+-   Added `useWeapon` documentation
+-   Added `useState` documentation
+-   Changed `update()` references to `sync()`
+-   Updated documentation for `useAudio` composable
+
 ## Version 5
 
 ### Code Changes

docs/webview/composables/use-audio.md

@@ -2,6 +2,8 @@
 
 Gives you the ability to play custom sounds from the Webview.
 
+If you wish to play frontend sounds check out the [Frontend Sound List](../../data/frontend-sounds.md).
+
 ```html
 <script lang="ts" setup>
     import { useAudio } from '../../../../webview/composables/useAudio';
@@ -10,5 +12,9 @@ Gives you the ability to play custom sounds from the Webview.
 
     // Play a simple custom sound
     audio.play('/sounds/my-cool-sound.ogg');
+
+    // Play a native frontend sound from the webview and invoke the native.
+    // audioName, audioRef, audioBank (Optional)
+    audio.playFrontendSound('NAV_LEFT_RIGHT', 'HUD_FRONTEND_DEFAULT_SOUNDSET');
 </script>
 ```

src/main/client/webview/index.ts

@@ -1,4 +1,5 @@
 import * as alt from 'alt-client';
+import * as native from 'natives';
 import { Events } from '@Shared/events/index.js';
 import { PageNames, PageType } from '@Shared/webview/index.js';
 
@@ -24,13 +25,32 @@ function handleClientEvent(event: string, ...args: any[]) {
     ClientEvents[event](...args);
 }
 
+async function handleFrontendSound(audioName: string, audioRef: string, audioBank = '') {
+    if (audioBank !== '') {
+        native.requestScriptAudioBank(audioBank, false, -1);
+    }
+
+    native.playSoundFrontend(-1, audioName, audioRef, true);
+}
+
 export function useWebview(path = 'http://assets/webview/index.html') {
     let isInitialized = true;
 
     if (!webview) {
+        isInitialized = false;
         webview = new alt.WebView(path);
         webview.unfocus();
-        isInitialized = false;
+        webview.on(Events.view.playFrontendSound, handleFrontendSound);
+        alt.on('keyup', emitKeypress);
+    }
+
+    /**
+     * Emits key presses to the webview
+     *
+     * @param {number} key
+     */
+    function emitKeypress(key: number) {
+        webview.emit(Events.view.onKeypress, key);
     }
 
     /**

src/main/server/document/character.ts

@@ -51,7 +51,9 @@ export function useCharacter(player: alt.Player) {
      * @param {(keyof KnownKeys<Character & T>)} fieldName
      * @return {ReturnType | undefined}
      */
-    function getField<T = {}, ReturnType = any>(fieldName: keyof KnownKeys<Character & T>): ReturnType | undefined {
+    function getField<T = {}, K extends keyof KnownKeys<Character & T> = keyof KnownKeys<Character & T>>(
+        fieldName: K,
+    ): (Character & T)[K] | undefined {
         if (!player.hasMeta(sessionKey)) {
             return undefined;
         }
@@ -290,13 +292,16 @@ export function useCharacter(player: alt.Player) {
     return { get, getField, isValid, getVehicles, permission, set, setBulk };
 }
 
-export function useCharacterBinder(player: alt.Player) {
+export function useCharacterBinder(player: alt.Player, syncPlayer = true) {
     /**
      * Binds a player identifier to a Character document.
      * This document is cleared on disconnected automatically.
      * This should be the first thing you do after having a user authenticate.
      *
+     * Pass `syncPlayer` as false to prevent synchronization of appearance and clothes on binding.
+     *
      * @param {Character & T} document
+     * @param {boolean} syncPlayer
      */
     function bind<T = {}>(document: Character & T): ReturnType<typeof useCharacter> | undefined {
         if (!player.valid) {
@@ -305,6 +310,14 @@ export function useCharacterBinder(player: alt.Player) {
 
         player.setMeta(sessionKey, document);
         Rebar.events.useEvents().invoke('character-bound', player, document);
+
+        if (syncPlayer) {
+            Rebar.player.usePlayerAppearance(player).sync();
+            Rebar.player.useClothing(player).sync();
+            Rebar.player.useWeapon(player).sync();
+            Rebar.player.useState(player).sync();
+        }
+
         return useCharacter(player);
     }
 

src/main/server/document/vehicle.ts

@@ -145,13 +145,18 @@ export function useVehicleBinder(vehicle: alt.Vehicle) {
      *
      * @param {Vehicle & T} document
      */
-    function bind<T = {}>(document: Vehicle & T): ReturnType<typeof useVehicle> | undefined {
+    function bind<T = {}>(document: Vehicle & T, syncVehicle = true): ReturnType<typeof useVehicle> | undefined {
         if (!vehicle.valid) {
             return undefined;
         }
 
         vehicle.setMeta(sessionKey, document);
         Rebar.events.useEvents().invoke('vehicle-bound', vehicle, document);
+
+        if (syncVehicle) {
+            Rebar.vehicle.useVehicle(vehicle).sync();
+        }
+
         return useVehicle(vehicle);
     }
 

src/main/server/index.ts

@@ -22,7 +22,7 @@ import {
     useCharacter,
     useCharacterBinder,
     useGlobal,
-    useVehicle,
+    useVehicle as useVehicleDocument,
     useVehicleBinder,
     useVehicleEvents,
     useVirtual,
@@ -45,13 +45,16 @@ import { useWebview } from './player/webview.js';
 import { useClothing } from './player/clothing.js';
 import { useAnimation } from './player/animation.js';
 import { usePlayerAppearance } from './player/appearance.js';
+import { useWeapon } from './player/weapon.js';
 
 import { useMessenger } from './systems/messenger.js';
 import { usePermission } from './systems/permission.js';
 import { usePermissionGroup } from './systems/permissionGroup.js';
 
 import { check, hash } from './utility/password.js';
 import { sha256, sha256Random } from './utility/hash.js';
+import { useVehicle } from './vehicle/index.js';
+import { useState } from './player/state.js';
 
 export function useRebar() {
     return {
@@ -88,7 +91,7 @@ export function useRebar() {
                 useGlobal,
             },
             vehicle: {
-                useVehicle,
+                useVehicle: useVehicleDocument,
                 useVehicleBinder,
                 useVehicleEvents,
             },
@@ -114,6 +117,8 @@ export function useRebar() {
             useClothing,
             useNative,
             useNotify,
+            useState,
+            useWeapon,
             useWebview,
             useWorld,
         },
@@ -132,5 +137,8 @@ export function useRebar() {
                 hash,
             },
         },
+        vehicle: {
+            useVehicle,
+        },
     };
 }