# 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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.0resmon.org/0resmon/0r-resources/0r-smarttab/hacking-app-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.