Tips & Tricks

This page provides practical advice, tips, and best practices for working with the heist system. Instead of repeating parameter documentation, we focus on the development workflow, common pitfalls, an

Development Workflow

Start Small, Expand Later

Tip: Begin with a minimal working heist and gradually add complexity.

1. First, create a heist with just one stage and a simple interaction

2. Test thoroughly before adding more stages

3. Add complexity one element at a time (NPCs, doors, rewards)

4. Test each addition before moving to the next

This approach helps isolate issues when they occur and makes troubleshooting much easier.

Debug and Development Mode

The system offers two special modes to help during development:

Debug Mode (debug = true in config.lua):

• Visualizes zones that are normally invisible

• Shows interaction points, render zones, and other elements

• Helps ensure everything is positioned correctly

• Intended purely for testing and development

Development Mode (dev_mode = true in config.lua):

• Bypasses item requirements for interactions

• Ignores police officer count requirements

• Allows using interactions that require a bag even without one

• Intended purely for testing and development

Important Note: Currently, to reset heists or apply configuration changes, you need to restart the script. There are no built-in commands for resetting heists dynamically.

Coordinate Gathering

When placing interaction points, use:

1. Use some tools to get your current position (x, y, z, heading)

2. For objects, stand directly in front of them

3. Note that interaction offsets may need adjustment - small tweaks of 0.1-0.2 units can make a difference

Common Pitfalls and Solutions

Interaction Placement

Problem: Players complain they can't interact with objects.

Solutions:

• Make sure distance is appropriate (usually 1.0-1.5)

• Verify the zone.pos is correctly positioned

• Check if your ox_target or qb_target settings are correct

• Adjust the size/dimensions to match the object

• Use the debug visualization to see if zones are positioned correctly

Stage Progression Issues

Problem: Players get stuck at a stage and can't progress.

Solutions:

• Check if you've included unlock_stage in your on_complete functions

• Verify the stage_id parameter is correct

• Ensure you haven't accidentally locked an interaction with lock_interaction

• Check if any prerequisites (like items) are too difficult to obtain

NPC Behavior Problems

Problem: NPCs aren't behaving as expected.

Solutions:

• Double-check the relationship value (5 = hostile, 3 = neutral)

• Verify that stage is set correctly so NPCs spawn at the right time

• Check if guards_friendly_with_police matches your intention

• For patrol routes, ensure positions are navigable by NPCs, some maps or interiors don't have AI navigation points.

• If NPCs are running away, check always_fight setting

Optimization Tips

Performance Considerations (WIP)

1. Limit NPC Count: Each NPC adds processing overhead. Use only as many as needed.

2. Laser Systems: Complex laser systems with many targets can be performance-intensive. Limit the number of laser points and keep them in a small area.

3. Gas Effects: Gas particles can impact performance. Use them sparingly and in strategic locations.

Location Selection

When choosing locations for heists, consider:

1. Server Population: Place heists in different areas of the map to avoid player congestion

2. Resource Usage: Avoid areas with many existing resources/scripts running

3. Interior Complexity: Complex interiors may already have performance impacts

4. MLO Compatibility: Ensure custom MLOs are stable and compatible with your server

Design Patterns and Techniques

Multi-Stage Design Pattern

A well-structured heist typically follows this pattern:

1. Entry Stage: Initial breach with alarm triggering (thermite, lockpick)

2. Security Bypass: Deal with security systems (hack, disable lasers)

3. Access Stage: Access the secured area (drill vault, torch door)

4. Loot Stage: Multiple interaction points for rewards

5. Escape Mechanics: Optional challenges for escaping

NPC Placement Strategy

Strategic NPC placement creates better gameplay:

1. Place guards at entry points for initial challenge

2. Position NPCs with find_target = false deeper in the heist to give players time to react

3. Set up "reinforcement" NPCs with higher stage values

4. Use varied weapons and skill levels for different NPCs

5. Consider setting some NPCs to patrol key areas

Reward Balancing

Balance risk vs. reward for a satisfying experience:

1. Distribute rewards through multiple stages to encourage completion

2. Use chance percentages (e.g., chance = 10) for rare items

3. Place higher-value rewards behind more difficult challenges

4. Consider the total value of all possible rewards to avoid economic imbalance

5. Use limit in rewards to control maximum obtainable items

Troubleshooting

When Interactions Don't Work

If an interaction isn't triggering:

1. Check if you're in the correct render zone

2. Verify item requirements are met

3. Make sure the stage is properly unlocked

4. Check if distance is appropriate

5. Look for syntax errors in your configuration

6. Ensure target system settings are correct

7. Try with debug = true to see additional information

8. Check the server console for errors

Debugging NPC Issues

If NPCs aren't spawning or behaving correctly:

1. Verify coordinates are valid (not inside objects)

2. Check if the stage value matches when you expect them to appear

3. Make sure relationship values are correct

4. For patrols, ensure the route is navigable

5. Check if weapons are valid hashes

6. Verify animations/scenarios are valid

Common Syntax Issues

Watch for these syntax mistakes:

1. Missing commas at the end of table entries

2. Incorrect nesting of tables

3. Missing closing brackets or parentheses

4. Using quotes around vector coordinates

5. Improper hash syntax (use backticks: `model_name`)

6. Case sensitivity in function names and parameters

Best Practices

Configuration Organization

Keep your configurations clean and maintainable:

1. Use consistent indentation (preferably tabs or 4 spaces)

2. Add comments to explain complex logic

3. Group related settings together

4. Use meaningful names for presets and identifiers

5. Keep deeply nested tables organized with proper indentation

Testing Process

Follow a methodical testing approach:

1. Test each interaction point individually

2. Verify stage progression works correctly

3. Test with different numbers of players

4. Check police response and alerts

5. Verify all rewards are obtainable

6. Test edge cases (player death, disconnects, server restarts)

7. Have others test your heist for an unbiased perspective

Resource Priority

Set appropriate resource start order:

1. Ensure frameworks load before the heist system

2. Target systems should load before heists

3. Any custom resources used by your heists should start first

4. Consider using ensure statements in your server.cfg