# Installing Ambitions

## Prerequisites

Before starting, make sure your environment meets all the following requirements:

### Functional FiveM Environment

* You must already have a working FiveM server (localhost or hosted).
* This guide assumes you followed the [**Environment Setup**](https://ambitions.gitbook.io/ambitions-documentation/environment-setup) section correctly.

### Artifact Requirements

* Must use **Windows artifacts newer than 12208**
* **Linux is not officially supported**, and no assistance will be given for Linux-related issues.

### Database Setup

* Recommended: **MariaDB + HeidiSQL**
* Refer to the [Database Setup](https://ambitions.gitbook.io/ambitions-documentation/environment-setup/database-setup) section if unsure.

{% hint style="danger" %}
⚠️ **XAMPP is not supported.** If you insist on using it, do so at your own risk. You are strongly advised to switch to MariaDB and HeidiSQL.
{% endhint %}

### Lua Version

* Your environment must support **Lua 5.4**
* All external scripts that connect with Ambitions must also be **compatible with Lua 5.4**

### Basic Knowledge Required

* You must understand:
  * Core Lua concepts (not just FiveM-specific ones)
  * How to debug, optimize, and configure scripts manually

{% hint style="warning" %}
**⚠️ If you lack programming experience: learn the basics or hire a developer.**
{% endhint %}

***

## Required Dependency

Ambitions only supports **oxmysql** as its database wrapper:

* **oxmysql** → [Visit oxmysql github page](https://github.com/CommunityOx/oxmysql)

{% hint style="warning" %}
**⚠️ Ambitions Studio provides no support for other wrappers such as `ghmattimysql` or `mysql-async`.**
{% endhint %}

***

## Database Connection

You must know how to connect your database to your FiveM server. If not, follow the documentation here: [**Connecting Database to FiveM**](https://ambitions.gitbook.io/ambitions-documentation/environment-setup/database-setup/link-your-database-to-fivem)

Also, know your stack: know what you're integrating and ensure compatibility.

***

## Installing the Framework

### Option A - GitHub Main Branch (recommended for developers)

1. Visit the [Ambitions GitHub Repository](https://github.com/Ambitions-Studio/Ambitions)
2. Ensure you're on the **`main` branch** (always stable)
3. Download the ZIP or clone the repo:
   * **ZIP**: Extract it inside your server's `resources/` folder
   * **Git**: `git clone https://github.com/AmbitionsStudio/Ambitions resources/Ambitions`

### Option B - Release Package (coming soon)

For easier integration, Ambitions will provide release bundles. Not yet available.

***

## Database Setup

1. Go to `Ambitions/sql`
2. Locate the `.sql` file (e.g. `ambitions_schema.sql`)
3. Import it into your database manually

{% hint style="warning" %}
**⚠️ Ambitions Studio does not offer tutorials on SQL imports. If you don't know how to import a `.sql` file, you should learn or ask someone who does.**
{% endhint %}

{% hint style="danger" %}
**⚠️ Again, using XAMPP may lead to issues. You're on your own if you insist.**
{% endhint %}

***

## Configuration

Navigate to `Ambitions/config/` — you'll find:

* `client/` → client-side configurations
* `server/` → server-side configurations
* `shared/` → shared logic and constants

Configure each file according to your project needs.

***

## Resource Startup Order

Open your `server.cfg` file and add the following **in this exact order**:

```editorconfig
ensure oxmysql
ensure Ambitions
```

{% hint style="warning" %}
**⚠️ Ambitions Studio does not provide help on how to write a `server.cfg`. You are expected to know this.**
{% endhint %}

***

## Final Step

Start your FiveM server and monitor the console:

* No errors = you're good to go
* Errors = debug them, check requirements, or ask in the ***(coming soon)*** Ambitions Studio Discord

#### You have now successfully installed the **Ambitions Framework**. You're ready to start building.