# Hacking App Usage

## HackApp (0r-smarttab) — External Usage Guide

This page explains how to open **HackApp** from other resources and receive the hack result as a **callback**.

HackApp is a **3-stage** hacking minigame (Network Breach → Privilege Escalation → Trace Removal) with randomized puzzles, timers, and mistake limits.

***

### Requirements

* **Resource**: `0r-smarttab` must be started.
* **Client-side usage**: use exports from the **client** context.
* **App action id**: HackApp is opened via app action id **`hack`** (the same value used in `apps.json`).

***

### Quick Start (Recommended)

Use the `StartHack` export. It opens the tablet directly on HackApp and returns a result object.

```lua
exports['0r-smarttab']:StartHack({ mode = 'fast' }, function(result)
  -- result = { success = boolean, sessionId = string|nil, data = table }
  if result.success then
    print('Hack succeeded!', result.sessionId)
  else
    print('Hack failed!', result.data and result.data.reason)
  end
end)
```

***

### Export API

#### `StartHack(options, cb)`

Opens the tablet and navigates to HackApp. When the hack finishes, `cb(result)` is called.

**Parameters**

* **options** *(table, optional)*
  * **mode** *(string, optional)*: `"fast"` | `"safe"` | `"brute"`
    * Note: HackApp also has an in-UI mode selection screen. Passing `mode` is for future extensions; the UI currently lets the player choose.
* **cb** *(function, required)*: called once with the hack result.

**Callback result**

`cb(result)` receives:

* **success** *(boolean)*: `true` on full 3-stage completion, otherwise `false`
* **sessionId** *(string|nil)*: unique hack attempt id
* **data** *(table)*: payload from the UI, includes context such as:
  * `mode` *(string)*
  * `deviceQuality` *(number)*
  * `skillLevel` *(number)*
  * on fail: `stage`, `reason`, `traceLevel`

**Timeout behavior**

If the player never starts/finishes the hack, the export auto-resolves after \~2 minutes:

```lua
{ success = false, sessionId = nil, data = { reason = 'timeout' } }
```

***

### Alternative: Open HackApp Manually

If you only want to open HackApp (no callback), use:

```lua
exports['0r-smarttab']:OpenTabletWithApp('hack')
```

***

### Event / NUI Flow (How the callback is produced)

HackApp runs in the tablet UI and reports results to Lua using NUI callbacks:

* **Success** → `fetchNui('hack:success', payload)`
* **Fail** → `fetchNui('hack:fail', payload)`

On the client, `0r-smarttab` forwards these to:

* Server events:
  * `0r-smarttab:server:hack:success`
  * `0r-smarttab:server:hack:fail`
* A local client event used to resolve `StartHack` callbacks:
  * `0r-smarttab:client:hack:result` *(internal)*

***

### Failure Consequences (Default Behavior)

By default, HackApp failure applies meaningful consequences:

* **Cooldown** (temporary)
* **Lockout** (temporary)
* **Heat** increases (temporary difficulty boost)
* Optional **police dispatch** trigger on higher trace levels

Server-side baseline hooks are implemented in `0r-smarttab/server/main.lua`:

* `0r-smarttab:server:hack:fail` triggers dispatch via:
  * `0r-smarttab:server:dispatch:hackFail`

If your server uses a custom dispatch resource, adapt the dispatch handler to your system.

***

### Example: Gate an Action Behind a Hack

```lua
local function StartDoorHack(doorId)
  exports['0r-smarttab']:StartHack({ mode = 'safe' }, function(res)
    if not res.success then
      -- Optional: react based on res.data.reason or res.data.traceLevel
      TriggerEvent('chat:addMessage', { args = { 'SYSTEM', 'Hack failed.' } })
      return
    end

    -- Hack success → proceed
    TriggerServerEvent('mydoors:server:unlockDoor', doorId)
  end)
end
```

***

### Troubleshooting

#### HackApp opens but callback never fires

* Ensure `0r-smarttab` is up-to-date (client NUI callbacks `hack:success` / `hack:fail` must exist).
* Verify your hack attempt reaches a result screen (success/fail). The callback is returned only on completion or timeout.

#### Tablet is not opening

* Confirm the player has the tablet item / permissions (your server rules).
* Confirm `0r-smarttab` is started and healthy.

***

### Version Notes

* This guide assumes the upgraded multi-stage HackApp and the `StartHack` export are present in your `0r-smarttab`.