# MyTutorial – Complete Documentation
> **For:** Server Admins and Plugin Developers
> **Purpose:** Introduce players to your server using a progressive tutorial system
---
## What is MyTutorial?
MyTutorial is a **progressive tutorial system** designed to help players understand your server mechanics.
It presents players with *tasks* that they must complete one after another.
**Example:**
The goal is to showcase all custom features, commands, locations, and events on your server to new players step by step:
1. Player connects → Task 1 displayed: "Open your inventory"
2. Player opens inventory → Task 1 ✓, Task 2 displayed: "Gather 100 Wood"
3. Player gathers wood → Task 2 ✓ → Tutorial completed
---
## How to Create a Tutorial
### Step 1: Open the Config
Open `oxide/config/MyTutorial.json`
### Step 2: Understand the Structure
The config file uses this **basic structure**:
```json
{
"TaskGroups": [
{
"Tasks": [
{
"Description": ["Task description text"],
"CompletionCondition": "ConditionType",
"CompletionType": "DataType",
"CompletionValue": "ValueToCheck"
}
]
}
],
"DefaultPosition": "MiddleLeft"
}
```
**What does this mean?**
- **TaskGroups**: Groups of tasks (multiple groups act as different "chapters" in your tutorial)
- **Tasks**: Individual tasks within a group
- **Description**: What the player sees in the UI (supports multiple lines)
- **CompletionCondition**: What action or state the player must fulfill to complete the task
- **DefaultPosition**: Where the tutorial window appears on the screen
---
## Task Types (CompletionCondition)
Choose a condition type based on **what you want the player to do**:
### 1. ItemInInventory – Item in Inventory
**Player must possess a specific item**
```json
{
"Description": ["⇨ Gather 5 Wood", " ⇝ Walk to a tree and cut it down"],
"CompletionCondition": "ItemInInventory",
"CompletionType": "shortname",
"CompletionValue": "wood"
}
```
**Multiple Items (OR condition):**
```json
"CompletionValue": "wood,stone,ore"
```
→ Completed if the player has **any one** of these items.
---
### 2. Command – Execute Chat Command
**Player must type a chat command**
```json
{
"Description": ["⇨ Open your character menu", " ⇝ Type /char"],
"CompletionCondition": "Command",
"CompletionType": "command",
"CompletionValue": "/char"
}
```
**Important:** The check matches as long as the command **starts with** the specified word.
- `/char` also fulfills: `/char builder`, `/char add`, etc.
**Multiple Commands (OR condition):**
```json
"CompletionValue": "/char,/character,/skills"
```
---
### 3. BuildingPlaced – Place Building / Entity
**Player must place a building piece or entity**
```json
{
"Description": ["⇨ Place a Workbench", " ⇝ Use building placement"],
"CompletionCondition": "BuildingPlaced",
"CompletionType": "shortname",
"CompletionValue": "workbench1"
}
```
---
### 4. Group – Player in Oxide Group
**Player must belong to a specific Oxide group**
```json
{
"Description": ["⇨ Become a VIP Member", " ⇝ Purchase a VIP package"],
"CompletionCondition": "Group",
"CompletionType": "group",
"CompletionValue": "vip"
}
```
**Multiple Groups (OR condition):**
```json
"CompletionValue": "vip,donor,supporter"
```
---
### 5. LocationVisit – Visit Location
**Player must enter a specific area**
```json
{
"Description": ["⇨ Visit the Marketplace", " ⇝ Head to the center"],
"CompletionCondition": "LocationVisit",
"CompletionType": "location",
"CompletionValue": "0,100,0,50"
}
```
**Format:** `X,Y,Z,Radius`
- **X, Y, Z**: Coordinates of the location
- **Radius**: Detection area size in meters
*Tip:* Use `printpos` in-youur F1 Console to get your current coordinates.
**Multiple Locations (OR condition):**
```json
"CompletionValue": "0,100,0,50,500,200,0,40"
```
---
### 6. Playtime – Required Playtime
**Player must have played for X seconds**
```json
{
"Description": ["⇨ Play for 1 Hour", " ⇝ Spend time on the server"],
"CompletionCondition": "Playtime",
"CompletionType": "seconds",
"CompletionValue": "3600"
}
```
**Examples:**
- `60` = 1 Minute
- `3600` = 1 Hour
- `86400` = 24 Hours
---
### 7. FarmRoute – Complete Farm Route
Plugin: https://codefling.com/plugins/farm-route
**Player must complete/interact with a FarmRoute zone** (requires FarmRoute plugin)
```json
{
"Description": ["⇨ Collect Weed", " ⇝ Go to the Weed Farm and harvest"],
"CompletionCondition": "FarmRoute",
"CompletionType": "route",
"CompletionValue": "weed:farming"
}
```
**Format:** `routename:type`
- **routename**: Name of the route in FarmRoute (lowercase!)
- **type**: `farming`, `converter`, or `buyer`
**Multiple Routes (OR condition):**
```json
"CompletionValue": "weed:farming,hemp:farming"
```
---
### 8. Plugin Integration – Special Server Menus
**Player must open a specific server plugin menu** (e.g., Bank, Black Market)
```json
{
"Description": ["⇨ Visit the Bank", " ⇝ Open the Bank menu"],
"CompletionCondition": "Command",
"CompletionType": "command",
"CompletionValue": "mybank"
}
```
**Available Plugin Integrations:**
- `mybank` – MyBank UI opened
- `openblackmarket` – Black Market UI opened
- `openmoneywash` – Money Wash UI opened
- `opentrader` – Resource Trader UI opened
*(You can find my plugins on my profile)*
---
## Practical Examples
### Example 1: Beginner Tutorial (First 5 Minutes)
```json
{
"TaskGroups": [
{
"Tasks": [
{
"Description": [
"⇨ Welcome to our server!",
" ⇝ This is your first tutorial task",
" ⇝ Open your inventory (TAB)"
],
"CompletionCondition": "ItemInInventory",
"CompletionType": "shortname",
"CompletionValue": "wood,stone"
},
{
"Description": [
"⇨ Gather some more wood",
" ⇝ Cut down a tree"
],
"CompletionCondition": "ItemInInventory",
"CompletionType": "shortname",
"CompletionValue": "wood"
}
]
}
],
"DefaultPosition": "MiddleLeft"
}
```
### Example 2: Intermediate Tutorial (Base Building)
```json
{
"TaskGroups": [
{
"Tasks": [
{
"Description": [
"⇨ Build your house",
" ⇝ Place a Tool Cupboard (TC)"
],
"CompletionCondition": "BuildingPlaced",
"CompletionType": "shortname",
"CompletionValue": "cupboard.tool"
},
{
"Description": [
"⇨ Secure your base",
" ⇝ Place a metal double door"
],
"CompletionCondition": "BuildingPlaced",
"CompletionType": "shortname",
"CompletionValue": "door.double.hinged.metal"
}
]
}
],
"DefaultPosition": "Center"
}
```
### Example 3: Economy Tutorial (Bank + Farming)
```json
{
"TaskGroups": [
{
"Tasks": [
{
"Description": [
"⇨ Open your bank account",
" ⇝ Type /bank or open the menu"
],
"CompletionCondition": "Command",
"CompletionType": "command",
"CompletionValue": "mybank"
}
]
},
{
"Tasks": [
{
"Description": [
"⇨ Farm Weed",
" ⇝ Go to the Weed Farming Zone",
" ⇝ Gather the seeds"
],
"CompletionCondition": "FarmRoute",
"CompletionType": "route",
"CompletionValue": "weed:farming"
},
{
"Description": [
"⇨ Process Weed",
" ⇝ Go to the Converter Zone"
],
"CompletionCondition": "FarmRoute",
"CompletionType": "route",
"CompletionValue": "weed:converter"
}
]
}
],
"DefaultPosition": "TopRight"
}
```
---
## UI Positions
Use `DefaultPosition` to define where the tutorial window appears on screen:
```
TopLeft TopCenter TopRight
MiddleLeft Center MiddleRight
BottomLeft BottomCenter BottomRight
```
**Example:**
```json
"DefaultPosition": "TopRight"
```
---
## Commands for Players
Players can use these commands (Permission: `mytutorial.use`):
| Command | Description |
| -------------------- | ----------------------------------------- |
| `/toggletutorial` | Toggle tutorial UI display (show/hide) |
| `/checktutorial` | Manually refresh/check progress |
| `/tutorialposition` | Cycle through UI positions |
---
## Permissions
Add this permission to your `permissions.cfg` or `groups.cfg` file:
```
mytutorial.use
```
---
## Frequently Asked Questions (FAQ)
### Q: The tutorial isn't showing up!
**A:** Please check:
1. Does the player have the `mytutorial.use` permission?
2. Is the config file free of syntax errors? (Validate JSON)
3. Was the plugin reloaded? (`oxide.reload MyTutorial`)
### Q: How many tasks should a tutorial have?
**A:**
- **Beginner Tutorial:** 3–5 tasks
- **Complete Tutorial:** 10–20 tasks
- Tutorials that are too long get tedious; overly short ones aren't helpful.
### Q: Can I use HTML/colors in the text?
**A:** **Yes!** You can use standard Rust text tags:
```json
"Description": [
"⇨ <color=#ffed00>Gather Wood</color>",
" ⇝ <size=16>Cut down a tree</size>"
]
```
**Common Tags:**
- `<color=#ffed00>` (Yellow)
- `<color=red>` (Red)
- `<color=green>` (Green)
- `<size=18>` (Size)
### Q: Is progress saved?
**A:** **Yes!** Player progress is saved automatically:
- On server restart
- On plugin reload
- Upon completing a task
### Q: Can I have multiple tutorials?
**A:** No, there is one tutorial active per server. However, you can include many TaskGroups within a single config.
### Q: What happens if a player skips a task?
**A:** Tasks cannot be skipped. The tutorial is progressive — tasks must be completed in order.
---
## Troubleshooting & Debugging
### JSON Error?
Use an online **JSON Validator**, e.g., https://jsonlint.com/
### Plugin not loading?
Check the server **Console**:
```
[MyTutorial] Error: ...
```
### Tasks not completing?
1. Verify **CompletionValue** – must match exactly
2. Verify **CompletionType** – must fit the condition type
3. Use `/checktutorial` in-game to trigger a manual check
---
## Workflow: New Tutorial in 5 Steps
1. **Open Config:** `oxide/config/MyTutorial.json`
2. **Add TaskGroups** with your tasks
3. **Save**
4. **Reload Plugin:** `oxide.reload MyTutorial`
5. **Test In-Game:** Reconnect and test the tutorial sequence
---
## Tips & Best Practices
**Do:**
- Short, clear descriptions
- Logical task order
- Colors for highlighting key words
- Structural icons/arrows (⇨, ⇝)
**Don't:**
- Overly long task lists
- Confusing or ambiguous language
- Impossible tasks (non-existent item names, etc.)
- Too many tasks all at once
---
## Support & More Info
If you have questions:
Good luck with your tutorial!