# CodeRanch - Animation Menu

**Advanced Animation System for RedM**

This script provides a comprehensive and modern animation system for RedM servers. Players can perform hundreds of animations, scenarios, emotes, dances, and walks with an intuitive UI. The system includes quick animation slots, duo animations, animation positioning, and prop attachments.

## 🚀 Features

* **500+ Animations**: Scenarios, emotes, dances, walks, and gestures
* **Quick Animation Slots**: Assign up to 4 animations to hotkeys (Shift+1-4)
* **Duo Animations**: Synchronized animations with other players
* **Animation Positioning**: Fine-tune animation position and rotation
* **Prop System**: Attach props like umbrella, coffee, lantern, guitar, etc.
* **Bench/Chair System**: Automatic sit detection on benches and chairs
* **Multi-Language Support**: Easy language customization
* **Config-Based**: Everything is configurable without touching the code
* **Database Integration**: Saves quick animations per player

## 📋 Requirements

* **RedM Server** (Latest recommended)
* **oxmysql** (For database connection)

## 🛠️ Installation

{% stepper %}
{% step %}

### Download Files

Copy the resource to your server's resources folder:

```bash
# Copy to your server's resources folder
resources/[coderanch]/coderanch-animations/
```

{% endstep %}

{% step %}

### Database Setup

The script will automatically create the table on first start:

```sql
-- The script will automatically create the table on first start
```

{% endstep %}

{% step %}

### Server.cfg Settings

Ensure dependencies and the resource are started:

```cfg
# Required dependencies
ensure oxmysql

# Animation Script
ensure coderanch-animations
```

{% endstep %}

{% step %}

### Configuration

Edit the config and language files to suit your server:

* `shared/config/config.lua`
* `shared/config/language.lua`
  {% endstep %}
  {% endstepper %}

## ⚙️ Configuration

### Menu Settings

```lua
Config.Menu = {
    command = "animmenu",      -- Command to open menu
    key = 0x80F28E95          -- Keyboard L key
}
```

### Quick Animation System

```lua
Config.QuickAnimations = {
    enable = true,
    firstPrefix = {
        label = "Shift",
        key = 0x8FFC75D6       -- Shift key
    },
    secondPrefixs = {
        { label = "1", key = 0xE6F612E4 },  -- Shift + 1
        { label = "2", key = 0x1CE6D9EB },  -- Shift + 2
        { label = "3", key = 0x4F49CC4C },  -- Shift + 3
        { label = "4", key = 0x8F9F9E58 }   -- Shift + 4
    }
}
```

### Duo Animation System

```lua
Config.DuoAnimations = {
    enable = true,
    commands = {
        request = "duoanim",       -- Request animation with another player
        accept = "acceptanim",     -- Accept incoming animation request
        reject = "rejectanim"      -- Reject incoming animation request
    },
    requestTimeout = 300,          -- Request expires after 5 minutes
    maxDistance = 10.0             -- Maximum distance between players
}
```

### Bench/Chair Sit System

```lua
Config.BenchCommand = {
    enable = true,
    command = "sit"               -- Command to sit on nearest bench
}
```

### Clear Ped Command

```lua
Config.ClearPedCommand = {
    enable = true,
    command = "clearped"          -- Command to clear all animations/props
}
```

### Animation Position System

```lua
Config.AnimPos = {
    enabled = true,
    movement_speed = 0.01,        -- Movement speed per key press
    rotation_speed = 2.0,         -- Rotation speed (degrees)
    scroll_speed = 0.08,          -- Mouse scroll speed
    
    keys = {
        -- Arrow keys for movement
        -- Q/E for rotation
        -- Enter to confirm, X to cancel
    }
}
```

### Prop Commands

```lua
Config.PropCommands = {
    {
        command = "umbrella",
        enable = true,
        model = "mp004_p_parasol04x",
        bone = "PH_R_Hand",
        offset = { x = 0.0, y = 0.0, z = 0.0 },
        rotation = { x = 0.0, y = 0.0, z = 0.0 },
        animDict = "amb_rest_drunk@world_human_drinking@moonshine@male_a@stand_enter_withprop",
        animName = "enter_back_lf",
        animFlag = 30
    },
    -- More prop configurations...
}
```

### Categories

```lua
Config.Categories = {
    { key = "scenerios", name = "Scenerios" },
    { key = "dances", name = "Dances" },
    { key = "emotes", name = "Emotes" },
    { key = "walks", name = "Walks" },
    { key = "animations", name = "Animations" }
}
```

### Notification System

```lua
Config.UseCodeRanchUI = true  -- Use coderanch-ui for notifications

-- Or use custom notification function
Config.SendNotification = function(message, type)
    -- Your notification system here
end
```

## 🎮 Usage

### For Players

#### Opening Animation Menu

* **Command**: `/animmenu` or press `L` key
* Browse through categories
* Search animations by name or command
* Click on animation to play

#### Quick Animations

{% stepper %}
{% step %}
Open animation menu
{% endstep %}

{% step %}
Right-click on any animation to select it
{% endstep %}

{% step %}
Click on a quick slot (bottom of menu) to assign
{% endstep %}

{% step %}
Use `Shift + 1-4` to play assigned animations
{% endstep %}

{% step %}
Right-click on quick slot to remove animation
{% endstep %}
{% endstepper %}

#### Playing Animations

* **Via Menu**: Click on animation in menu
* **Via Command**: `/e [animation_command]`
  * Example: `/e sit`, `/e dance`, `/e smoke`
* **Clear Animation**: `/e c` or `/e clear`

#### Duo Animations

{% stepper %}
{% step %}
Stand near another player
{% endstep %}

{% step %}
Use: `/duoanim [animation_name] [player_id]`
{% endstep %}

{% step %}
Other player accepts: `/acceptanim`
{% endstep %}

{% step %}
Other player rejects: `/rejectanim`
{% endstep %}
{% endstepper %}

#### Animation Positioning

{% stepper %}
{% step %}
Start any animation
{% endstep %}

{% step %}
Use command: `/animpos`
{% endstep %}

{% step %}
Use controls to adjust:

* Arrow Keys: Move forward/back/left/right
* Scroll Wheel: Move forward/backward
* Arrow Up/Down: Adjust height
* Q/E: Rotate left/right
* Enter: Confirm position
* X: Cancel
  {% endstep %}
  {% endstepper %}

#### Sitting on Benches

* Use command: `/sit` near a bench or chair
* Automatically detects available seats
* Use `/sit` again to stand up

#### Prop Commands

* `/umbrella` - Attach umbrella
* `/coffee` - Attach coffee mug
* `/lantern` - Attach lantern
* `/newspaper` - Read newspaper
* `/sack` - Carry sack
* `/flowers` - Hold flowers
* `/beer` - Hold beer bottle
* `/guitar` - Hold guitar
* `/map` - Read map

#### Clear All

* `/clearped` - Removes all animations and attached props

## 🔧 Advanced Settings

### Adding New Animation

Open `shared/config/animations.lua` and add to `Config.Animations`:

#### Scenario Animation

```lua
{
    name = "My Scenario",           -- Display name in menu
    category = "scenerios",         -- Category key
    type = "scenerio",              -- Type: scenerio
    scenerio = "WORLD_HUMAN_SMOKE", -- Scenario hash
    command = "mysmoke",            -- Command: /e mysmoke
    settings = {
        duration = -1               -- -1 = infinite, or milliseconds
    }
}
```

#### Regular Animation

```lua
{
    name = "My Animation",
    category = "emotes",
    type = "animation",
    dict = "amb_misc@world_human_cower",  -- Animation dictionary
    anim = "cower_outro",                  -- Animation name
    command = "mycower",
    settings = {
        duration = 5000,                   -- Duration in milliseconds
        flag = 0,                          -- Animation flag
        blendIn = 1.0,                     -- Blend in speed
        blendOut = 1.0                     -- Blend out speed
    }
}
```

#### Walk Style

```lua
{
    name = "My Walk",
    category = "walks",
    type = "walk",
    styleName = "FEMALE_NORMAL",          -- Walk style hash
    command = "mywalk"
}
```

#### Duo Animation

```lua
{
    name = "Duo Dance",
    category = "dances",
    type = "duo",
    dict = "amb_misc@world_human_dance",
    anim = "dance_01",
    command = "duodance",
    settings = {
        duration = -1,
        flag = 1,
        isDuo = true
    }
}
```

### Adding New Category

{% stepper %}
{% step %}
Add the category to the config (`shared/config/config.lua`):

```lua
Config.Categories = {
    -- Existing categories...
    {
        key = "mycategory",
        name = "My Category"
    }
}
```

{% endstep %}

{% step %}
Add an optional category icon:

* Place icon image in `web/src/assets/mycategory-icon.png`
  {% endstep %}

{% step %}
Add language entry (`shared/config/language.lua`):

```lua
Language.UI.categories = {
    -- Existing categories...
    mycategory = "My Category"
}
```

{% endstep %}
{% endstepper %}

### Adding New Prop Command

Add to `Config.PropCommands` in `shared/config/config.lua`:

```lua
{
    command = "myprop",                    -- Command name
    enable = true,                         -- Enable/disable
    model = "p_bottleBeer01a",            -- Prop model hash
    bone = "PH_R_Hand",                   -- Bone name to attach
    offset = { x = 0.0, y = 0.0, z = 0.0 }, -- Position offset
    rotation = { x = 0.0, y = 0.0, z = 0.0 }, -- Rotation offset
    animDict = "amb_rest_drunk@world_human_drinking@moonshine@male_a@stand_enter_withprop",
    animName = "enter_back_lf",
    animFlag = 30,
    attachDelay = 0                        -- Optional delay before attaching (ms)
}
```

Common bone names:

* `PH_R_Hand` - Right hand
* `PH_L_Hand` - Left hand
* `SKEL_Head` - Head
* `SKEL_Spine3` - Upper back
* `SKEL_L_Foot` - Left foot
* `SKEL_R_Foot` - Right foot

### Customizing Language

Edit `shared/config/language.lua`:

```lua
Language.Notifications = {
    no_animation_active = "No animation active!",
    bench_full = "Bench is full!",
    -- Add more messages...
}

Language.UI = {
    menu_title = "Animation Menu",
    search_placeholder = "Search...",
    exit_button = "Exit",
    -- Customize UI texts...
}
```

### Customizing Animation Position Controls

Edit `Config.AnimPos.keys` in `shared/config/config.lua`:

```lua
keys = {
    ["movement"] = {
        category = "Movement",
        keys = {
            {
                label = "Forward",
                key = "Scroll up",
                hash = 0x3076E97C  -- Key hash
            },
            -- Add more keys...
        }
    }
}
```

### Changing Quick Animation Hotkeys

Edit `Config.QuickAnimations.secondPrefixs`:

```lua
secondPrefixs = {
    { label = "F1", key = 0x3B24C470 },  -- F1
    { label = "F2", key = 0x433A4B3E },  -- F2
    { label = "F3", key = 0x26E9DC00 },  -- F3
    { label = "F4", key = 0x43DBF61F }   -- F4
}
```

## 📊 Database Structure

```sql
CREATE TABLE IF NOT EXISTS `coderanch_animations` (
    `identifier` VARCHAR(100) NOT NULL,
    `quickAnimations` LONGTEXT NULL DEFAULT NULL,
    PRIMARY KEY (`identifier`)
);
```

## Building UI Changes

```bash
cd web
npm install
npm run build
```

## 🐛 Troubleshooting

{% stepper %}
{% step %}
Menu Not Opening

* Check if key bind conflicts with other scripts
* Try using command `/animmenu` instead
* Check F8 console for errors
  {% endstep %}

{% step %}
Animations Not Playing

* Ensure animation dictionary/scenario exists in game
* Check animation command spelling
* Some animations require specific conditions
  {% endstep %}

{% step %}
Quick Animations Not Saving

* Check database connection
* Ensure oxmysql is running
  {% endstep %}

{% step %}
Props Not Attaching

* Check prop model hash is correct
* Verify bone name exists
* Adjust offset/rotation values
  {% endstep %}

{% step %}
Duo Animations Not Working

* Both players must be within max distance
* Ensure other player accepts request
  {% endstep %}

{% step %}
Animation Position Not Working

* Start an animation first before using `/animpos`
* Check key binds don't conflict
* Ensure `Config.AnimPos.enabled = true`
  {% endstep %}
  {% endstepper %}

## 📝 Commands Reference

### Player Commands

| Command                | Description                      |
| ---------------------- | -------------------------------- |
| `/animmenu` or `L`     | Open animation menu              |
| `/e [anim]`            | Play animation by command        |
| `/e c` or `/e clear`   | Clear current animation          |
| `/sit`                 | Sit on nearest bench/chair       |
| `/clearped`            | Clear all animations and props   |
| `/animpos`             | Enter animation positioning mode |
| `/duoanim [anim] [id]` | Request duo animation            |
| `/acceptanim`          | Accept duo animation request     |
| `/rejectanim`          | Reject duo animation request     |

### Prop Commands

| Command      | Description          |
| ------------ | -------------------- |
| `/umbrella`  | Attach umbrella prop |
| `/coffee`    | Attach coffee mug    |
| `/lantern`   | Attach lantern       |
| `/newspaper` | Attach newspaper     |
| `/sack`      | Attach sack          |
| `/flowers`   | Attach flowers       |
| `/beer`      | Attach beer bottle   |
| `/guitar`    | Attach guitar        |
| `/map`       | Attach map           |

## 🔄 Updates

### v1.0.0

* Initial release
* 500+ animations
* Modern UI with categories
* Quick animation system
* Duo animations
* Animation positioning
* Prop system
* Bench/chair detection
* Multi-language support
* Database integration

## 💡 Tips & Best Practices

1. Performance: The menu loads animations in chunks (100 at a time) for better performance
2. Quick Slots: Assign your most-used animations to quick slots for fast access
3. Animation Positioning: Use this feature for precise RP scenarios (sitting at tables, etc.)
4. Duo Animations: Great for RP scenarios like dancing, fighting choreography, etc.
5. Props: Combine props with animations for enhanced roleplay
6. Categories: Organize custom animations into appropriate categories
7. Commands: Use short, memorable commands for frequently used animations

## 📄 License

This script is developed by CodeRanch. Commercial use requires permission.


---

# 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://coderanch-redm-store.gitbook.io/coderanch-redm-store-docs/coderanch-animation-menu.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.