Introduction

This page explains the purpose, structure, and mechanics of the Ambitions importation system — the core mechanism that powers modular and context-aware resource design.

What Integration Does

Before using Ambitions in your resource, it's essential to understand what integration actually brings to the table:

• Establishes a clear connection between your resource and the framework core.

• Grants access to utility functions, shared logic, and performance-focused systems.

• Aligns your code with Ambitions' modular and scalable architecture.

In other words: it prepares your script to benefit from the clean, structured, and maintainable environment provided by the Ambitions ecosystem.

---

Why Integration Is Required

Ambitions is not a legacy-style monolithic framework. It relies on modular imports and context-aware execution. This design requires your resource to properly declare its intent and integration path.

When you integrate:

• ✅ You unlock shared modules, utility logic, and contextual helpers.

• ✅ You benefit from the class system, import logic, and error tracing.

• ✅ You ensure that your resource behaves predictably across environments (client, server, shared).

This is a necessary step to build scalable, reliable, and production-ready resources inside the Ambitions environment.

---

Resource Contexts

Ambitions applies strict logic separation per environment:

• client/ → Code meant to run only on the player’s machine

• server/ → Code that executes on the server-side

• shared/ → Logic or configurations shared across both contexts

Each module is loaded according to its declared context. When integrating, your fxmanifest.lua should declare:

shared_script '@Ambitions/importation.lua'

This enables contextual awareness when importing. The import system will smartly route your import requests based on runtime (client/server) and fallback to shared/ when applicable.

---

What Happens When You Integrate

When you add the @Ambitions/importation.lua to your fxmanifest.lua, Ambitions:

• Does not expose any global objects (ESX, QBCore, etc.)

• Exposes two clean import helpers:

Import()      -- For Lua modules and function resolution
ImportJson()  -- For indexed JSON file or full JSON structure loading

These helpers:

• Use scoped loading with fallback logic

• Allow cross-resource access

• Offer partial table extraction via key resolution

• Perform runtime validation (errors, tracebacks, feedback)

It's like require() — but adapted and enhanced for FiveM and Ambitions standards.

---

How It Works (Behind the Scenes)

The import system uses an internal logic built around:

1. Resource context awareness: client/server/shared resolution

2. Index files: shared.index.lua, client.index.lua, etc., that expose key-to-path mappings

3. Import types supported:

   • Import('module.path')

   • Import('@Resource.module.path')

   • Import('ModuleName', '@Resource')

   • Import('ModuleName:key', '@Resource')

   • Import({'ModuleA', 'ModuleB:key'}, '@Resource')

For JSON:

• ImportJson('path.to.file')

• ImportJson('@Resource.path.to.file')

• ImportJson('jsonKey', '@Resource')

• ImportJson({'key1', 'key2'}, '@Resource')

These import styles all resolve through a caching layer, context detection, and file fallback logic defined in the Lua system you’ve implemented.

Ambitions' import engine avoids unnecessary overhead, prevents circular dependencies, and ensures your resources stay clean, scoped, and explicit.

---

What’s Next?

Now that your resource is integrated with Ambitions, you're ready to:

• Use Import() to bring in logic, classes, or utilities from any resource (yours or Ambitions')

• Use ImportJson() to load configurations dynamically or destructure specific sections

• Declare your modules and exports cleanly

✅ Head over to the next page: Using the Importation System to learn how to perform specific imports and how to structure your own modules for reuse.