OnAdventGiftAward
OnAdventGiftAward is called when an AdventCalendar.AwardGift runs, right before the calendar computes the day and hands the player their reward. Returning a non-null value cancels the award.
object OnAdventGiftAward(AdventCalendar adventCalendar, BasePlayer player)Parameters
| Parameter | Type | Description |
|---|---|---|
adventCalendar | AdventCalendar | The AdventCalendar entity that is handing out the gift. Use it to read its position, net ID or owner, or to inspect the current day state. |
player | BasePlayer | The BasePlayer who triggered the award. Always null-check it and its connection before giving items or sending messages. |
Return value
Return null (or nothing, since the hook is declared object) to let the calendar award its gift normally. Returning any non-null value, including false, makes AwardGift return immediately, so no gift is given and day progress for that call is not advanced.
How it works
The hook fires inside AdventCalendar.AwardGift(BasePlayer), before the calendar reads DateTime.Now, resolves the day offset and proceeds with the normal gift logic. It runs once per award attempt, so it fires when a player interacts with a placed advent calendar to open the current day's gift (and whenever game code calls AwardGift directly, for example via command or admin tooling).
adventCalendar is the calendar entity performing the award; from it you can read transform.position, net.ID.Value or OwnerID to scope rules per entity. player is the recipient, useful for permission checks, inventory checks or team checks. Because the injection tests != null, any non-null return (even false or 0) returns from AwardGift early and the player gets nothing. Return null to let the vanilla gift happen.
Declaring player as BasePlayer matches the game signature exactly. There is no useful narrowing here: the argument is always a BasePlayer, and Oxide dispatches the hook before the method body runs, so filtering by type gains nothing. Do your filtering inside the hook body instead.
Example plugin: Require a permission before claiming an advent gift
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Advent Gift Permission", "RustPluginGenerator", "1.0.0")]
[Description("Requires a permission before a player can claim an advent calendar gift.")]
public class AdventGiftPermission : RustPlugin
{
private const string PermUse = "adventgiftpermission.use";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Grant permission to admins on load")]
public bool GrantToAdmins { get; set; } = true;
}
protected override void LoadDefaultConfig() => config = new PluginConfig();
protected override void LoadConfig()
{
base.LoadConfig();
try
{
config = Config.ReadObject<PluginConfig>();
if (config == null) throw new Exception();
}
catch
{
PrintWarning("Configuration file is invalid, using defaults");
LoadDefaultConfig();
}
SaveConfig();
}
protected override void SaveConfig() => Config.WriteObject(config);
protected override void LoadDefaultMessages()
{
lang.RegisterMessages(new Dictionary<string, string>
{
["NoPermission"] = "You need the adventgiftpermission.use permission to claim advent gifts."
}, this);
}
private string Msg(string key, string userId = null, params object[] args) =>
string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
permission.RegisterPermission(PermUse, this);
if (config.GrantToAdmins && permission.GroupExists("admin"))
{
permission.GrantGroupPermission("admin", PermUse, this);
}
}
private void Unload()
{
if (permission.GroupHasPermission("admin", PermUse))
{
permission.RevokeGroupPermission("admin", PermUse);
}
}
private object OnAdventGiftAward(AdventCalendar adventCalendar, BasePlayer player)
{
if (adventCalendar == null || player == null || player.net?.connection == null)
{
return null;
}
if (permission.UserHasPermission(player.UserIDString, PermUse))
{
return null;
}
player.ChatMessage(Msg("NoPermission", player.UserIDString));
return false;
}
}
}The plugin gates AwardGift behind the adventgiftpermission.use permission. When a player without it triggers a calendar, the hook returns a non-null value, which cancels the award, and the player receives a localized message explaining that they need the permission. Players with the permission fall through with null, so the vanilla gift logic runs untouched. On startup the plugin registers the permission and, if configured, grants it to the admin group so server staff can test immediately. Unload unregisters the permission so a reload always applies config changes cleanly.
Common use cases
Permission-gated advent events
Only let players with a donor or event permission claim gifts from placed advent calendars, cancelling everyone else and replying with a chat message.
Team or owner restrictions
Check
adventCalendar.OwnerIDor the player's team before awarding, so only the base owner and their teammates can open a calendar placed on the base.Inventory space guard
Return non-null when the player's main and belt containers are near full, preventing the gift from being dropped on the ground and lost.
Pitfalls
Any non-null value cancels
Returning
falsedoes not mean 'allow'; it is non-null, so the award is cancelled. Always returnnullwhen you want the vanilla path to continue.No feedback by default
Cancelling silently gives the player nothing and no message. Send a localized reply via
langbefore returning a value, otherwise it looks like a bug.Not the completion hook
This fires before the gift is computed. To react after a successful claim, use
OnAdventGiftAwardedinstead of doing reward bookkeeping here.
Build a plugin with OnAdventGiftAward
Describe what should happen and get a compiled plugin that uses this hook.
Edit the prompt on the next screen. 2 free plugins a month, no card.
Last updated Oct 26, 2026. Found a mistake? Email support@rustplugingenerator.com.
Build a plugin with OnAdventGiftAward
Generate