> For the complete documentation index, see [llms.txt](https://tg-dev.gitbook.io/tg-dev-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tg-dev.gitbook.io/tg-dev-docs/tg-cornerselling/install.md).

# Install

1. Place the resource in your server resources folder.

```
resources/[scripts]/tg-cornerselling
```

2. Install and configure all required dependencies.
3. Make sure every item used in `Config.Items` also exists in your inventory system. Item names must match exactly.
4. Configure `config/config.lua`.
5. Check the user-editable settings at the top of `config/bridge.lua`. The default automatic setup is recommended:

```lua
TGBridge.Settings = {
    UseCommunityBridge = true,
    CommunityBridgeResource = 'community_bridge',

    Core = {
        System = 'auto',
        -- ...
    },

    Inventory = {
        System = 'auto',
        -- ...
    },
}
```

6. Add the resources to `server.cfg` in the correct order. The framework and inventory entries below are examples; start only the systems used by your server.

```cfg
ensure oxmysql
ensure ox_lib

ensure es_extended
ensure ox_inventory

ensure community_bridge
ensure tg-cornerselling
```

For QB-Core or Qbox, replace the framework and inventory lines with your own resources.

7. Make sure OneSync is enabled.

```cfg
set onesync on
```

8. Restart the server and check the FXServer console.

No SQL file needs to be imported. The required tables are created automatically when the resource starts. A working `oxmysql` connection is still required.

> The startup config checker stays silent when the config is valid. If it finds an error, it prints the exact config path and prevents the gameplay systems from starting with invalid settings.

### First Setup Checklist

Before opening the server to players:

* Confirm that all configured items exist in the inventory.
* Confirm that `Config.General.Payment.Account` is valid for your framework.
* Select the correct language and currency.
* Review allowed, blocked, and police jobs.
* Review every area's coordinates, radius, buyers, and items.
* Test item images in the player panel.
* Test at least one accepted, refused, stolen, and dispatch outcome.
* Confirm that `/csadmin` is restricted to your administrators.
* Configure external logs if you want Discord or FiveManage logging.

### Commands

Command names can be changed under `Config.General.Commands`.

| Default command | Side   | Access           | Description                                |
| --------------- | ------ | ---------------- | ------------------------------------------ |
| `/cs`           | Client | Eligible players | Opens the player profile and selling panel |
| `/csadmin`      | Client | Administrators   | Opens the administration panel             |

### How Players Use the System

1. Open the profile with `/cs`.
2. Open the **Areas** page and choose a selling area.
3. Check which items are unlocked and currently accepted in that area.
4. Travel inside the area's configured radius.
5. Press **Start Selling**.
6. Approach an available buyer and interact using the configured key or target system.
7. Accept the original offer or optionally try a higher-price negotiation.
8. Continue selling until the player stops selling or the area's buyer pool becomes unavailable.

The Street Operation HUD displays the current buyer status, level progress, reputation, Heat, and session-only successful sales, failed sales, and earnings.

### Player Profiles

A permanent profile is created when an eligible player successfully opens `/cs` for the first time. Players who cannot access the script do not receive an unnecessary database profile and do not appear in rankings.

Persistent player records and local settings cover:

* Level and XP
* Reputation and street grade
* Heat
* Connection Points and purchased skills
* Lifetime statistics
* Recent deal history
* Daily and weekly challenges
* Career milestones
* Crew membership
* HUD preferences
* Mugshot used by crew member lists

### Progression

#### Level and XP

The default maximum player level is `50`. Completed sales, recovered stolen goods, and challenge rewards can grant XP.

Each level after level 1 awards one Connection Point. At maximum level, the normal level-up track provides 49 points.

#### Career milestones

One-time milestones reward the remaining Connection Points needed to complete the full skill tree. Their goals are based on long-term sales, revenue, items sold, negotiation wins, and clean sales.

#### Reputation

Reputation represents the player's standing on the street. It affects deal calculations and unlock requirements.

Default grades:

| Reputation | Grade      |
| ---------: | ---------- |
|          0 | New Dealer |
|        300 | Runner     |
|        750 | Dealer     |
|       1150 | Broker     |
|       1550 | Operator   |
|       1900 | Kingpin    |

The default maximum reputation is `2000`.

#### Heat

Heat represents police attention and selling risk. Higher Heat can reduce favorable outcomes, make negotiations harder, and increase dispatch risk. Heat falls automatically over time according to `Config.Progression`.

The default Heat range is `0–100`.

#### Connections

Connections are permanent player skills divided into three branches:

* **Profit:** payout, larger orders, price protection, and valuable buyer selection
* **Influence:** negotiation, reputation, buyer reading, and closing power
* **Safety:** outcome protection, Heat reduction, dispatch reduction, and shorter cooldowns

Some skills require a specific rank in the previous skill. Players can respec their skills by paying the configured price.

### Buyer Outcomes

Every completed buyer interaction ends with a server-calculated result:

| Outcome  | Meaning                                                               |
| -------- | --------------------------------------------------------------------- |
| Accepted | The sale succeeds, items are removed, and payment/rewards are granted |
| Refused  | The buyer rejects the deal                                            |
| Spooked  | The buyer backs out and may cause a dispatch report                   |
| Stolen   | The buyer takes the goods and runs without paying                     |
| Informed | The buyer reports the player                                          |

If goods are stolen, the player can recover them by killing the marked buyer and interacting with the body before the recovery time expires. If the recovery window expires, the goods are lost.

### Negotiation

When negotiation is enabled, players can ask for a higher price or a larger order. Each option has its own:

* Price increase
* Extra item amount
* Acceptance modifier
* Aggressive rejection modifier
* Patience cost
* Risk tone

Buyer patience is limited. A buyer who refused a smaller offer will not later accept a more demanding offer from the same negotiation chain.

All prices, chances, item amounts, and results are calculated by the server. The client only sends the selected option ID.

### Buyer Personalities

Buyer personalities make offers less predictable. For example, a desperate buyer may accept more goods, while a cautious buyer may pay less and report suspicious activity more often.

Each personality can change:

* Patience
* Requested item amount
* Payout
* Negotiation chance
* Aggressive rejection chance
* Dispatch chance
* Heat impact
* Outcome weights

Personality selection is weighted with the `weight` value in `Config.BuyerPersonalities`.

### Buyer Pools

Buyer availability is shared and synchronized by the server.

* Buyers are streamed only when players are nearby.
* A buyer becomes unavailable after being used.
* The area refresh timer begins when the remaining buyer count falls below `RefreshThreshold`.
* Buyer availability returns after the configured cooldown.
* Stolen-goods buyers remain protected long enough for their owner to attempt recovery.

`BuyerBlips` can be disabled separately for each area without disabling the selling system or the area's main map blip.

### Demand

Demand is tracked independently for every **area and item pair**. The same item can therefore have different demand in two different areas.

* Higher demand increases the sale price and selection weight.
* Completed sales reduce demand.
* Demand gradually moves toward a changing market target.
* Demand and active market timers survive resource restarts.

Default demand states are:

| Demand | State  |
| -----: | ------ |
|   0–34 | Cold   |
|  35–69 | Steady |
| 70–100 | Hot    |

### Market Events

Each area can run one server-authoritative market event at a time. Event timers are independent for each area and only run for areas that contain buyers.

The default event pool includes:

* Supply Shortage
* Market Flood
* Police Crackdown
* Night Rush
* Payday Rush
* Bulk Orders
* Quiet Streets
* Tough Crowd
* Fresh Faces

Events can change demand targets, payout, requested amount, negotiation chance, dispatch risk, and Heat. `Night Rush` only becomes eligible during its configured in-game hours.

Players can read all current event effects from the Market Intel guide in the Areas page.

### Challenges

Players receive rotating daily and weekly challenges.

* Daily and weekly selections are shared consistently for the same period.
* Rewards can include XP, reputation, and Connection Points.
* Rewards must be claimed from the challenge panel.
* Goals that cannot be completed with the current area, buyer, or item configuration are excluded.
* When a progression track is already capped, unusable reward parts can be converted into a small cash reward.

The reset hour uses UTC and is configured with `Config.Challenges.ResetHourUTC`.

### Crews

Players can create a crew, invite other players with six-digit invite codes, and build shared progression.

Default crew roles:

| Role      | Permissions                                                                            |
| --------- | -------------------------------------------------------------------------------------- |
| Boss      | Full crew management, perks, boosts, contracts, roles, invites, and ownership transfer |
| Recruiter | Can invite new members                                                                 |
| Member    | Can contribute and view crew progression                                               |

Crew features include:

* Maximum member limit
* Membership cooldown
* Crew level and XP
* Crew Credits
* Permanent perks
* Weekly crew contracts
* Momentum bonuses
* One active temporary boost
* Lifetime crew and member contribution statistics
* Crew rankings
* Member mugshots

Crew contracts are rewarded automatically after the target and minimum contributor requirement are met. Crew Credits cannot be withdrawn as player money; they are used for crew systems such as temporary boosts and perk respec.

Momentum rewards active teamwork. It gains value from sales, clean sales, negotiation wins, and contributor diversity. Its bonuses require the configured number of recent contributors and decay after inactivity.

### HUD Settings

Players can open HUD Settings from their profile to:

* Move each HUD element
* Change the scale of each HUD element
* Enable or disable individual HUD elements
* Reset visibility, scale, and position to defaults

HUD preferences are stored per player using the configured KVP key.

### Administration Panel

Open the administration panel with `/csadmin`.

Available tools include:

* Server and economy overview
* Live selling sessions
* Canceling an active selling session
* Global or area-specific operation controls
* Player search and profile inspection
* Editing level, XP, reputation, Heat, and Connection Points
* Resetting a profile or its skills
* Temporarily or permanently blocking a player from selling
* Resetting a player's crew membership cooldown
* Crew search, member inspection, role management, member removal, and crew actions
* Area inspection
* Buyer reset and buyer pool reset
* Market event reroll and ending active events
* Demand reset
* Real-time item price editing
* Filterable sale, crew, progression, admin, and system logs

Price changes made in the admin panel take effect immediately and are stored in `config/price_overrides.lua`, so they remain active after a resource or server restart.

> `config/price_overrides.lua` is managed by the resource. Use the in-game price editor instead of manually editing this file.

#### Admin permissions

Admin menu access is controlled by `Config.General.AdminPermissions`. Every admin callback checks this permission on the server; opening the NUI does not grant access by itself.

| Mode        | Access rule                                                              |
| ----------- | ------------------------------------------------------------------------ |
| `auto`      | A configured framework group **or** ACE permission is enough             |
| `framework` | Only configured framework groups are accepted                            |
| `ace`       | Only configured ACE permissions are accepted                             |
| `both`      | The player must pass a configured framework group **and** ACE permission |

The default settings preserve automatic ESX, QB-Core, Qbox, and common ACE admin detection:

```lua
AdminPermissions = {
    Mode = 'auto',

    FrameworkGroups = {
        admin = true,
        superadmin = true,
        god = true
    },

    ACEPermissions = {
        command = true,
        ['command.csadmin'] = true,
        ['command.admin'] = true,
        admin = true,
        god = true
    }
}
```

To allow only the `god` framework permission:

```lua
AdminPermissions = {
    Mode = 'framework',
    FrameworkGroups = {
        god = true
    },
    ACEPermissions = {}
}
```

To allow only a dedicated ACE permission:

```lua
AdminPermissions = {
    Mode = 'ace',
    FrameworkGroups = {},
    ACEPermissions = {
        ['tg-cornerselling.admin'] = true
    }
}
```

```cfg
add_ace group.admin tg-cornerselling.admin allow
```

Each table entry is an exact permission name. Entries set to `false` are ignored. When the admin command is renamed, update `command.csadmin` too if you use that command-specific ACE. Qbox servers should normally use `Mode = 'ace'` because Qbox uses ACE permissions for administrative access.