> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing an event to power an event-based achievement

> Sample XblEventsWriteInGameEvent code that fires a game event so XBOX services stat rules update stats and unlock event-based achievements.

This topic shows example code of how to write an in-game event.

When the event is fired, the event-based stats on the service are updated according to the stat rules that you've defined in Partner Center.
Those stats, in turn, power event-based achievements.

## Before you begin

* Your product uses the full XBOX services feature set. New products start with limited XBOX services, and achievements and gamerscore aren't available until your product is onboarded. For more information, see [Request product onboarding to enable full XBOX services](https://docs.xbox.com/home/onboarding.md#request-product-onboarding-to-enable-full-xbox-services).
* You configured the event, stat rules, and achievement in Partner Center and published the XBOX services configuration to your development sandbox.
* Your dev kit or Windows PC uses the same development sandbox, and you sign in with a test account that has access to that sandbox. For more information, see [XBOX services sandboxes overview](https://docs.xbox.com/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md).
* Your game initialized the Gaming Runtime and then called [XblInitialize](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize.md) with an [XblInitArgs](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/structs/xblinitargs.md) structure whose `scid` member contains your Service Configuration ID (SCID). The SCID is case-sensitive. For more information, see [How to use XBOX services APIs](https://docs.xbox.com/services/xbox-services/fundamentals/xbox-services-api/live-gs-xbl-apis.md).
* You signed in a user and created an `XblContextHandle` for that user by calling [XblContextCreateHandle](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle.md).

To reset achievements and stats for a test account between test runs, use the [Player Data Reset tool (XblPlayerDataReset.exe)](https://docs.xbox.com/tools/tools-services/live-player-data-reset.md). To reset a player by XUID, the developer account that you sign in with by using XblDevAccount.exe needs the product-level Tools Access permission.

## Write the event

The following example uses the flat C API. `LogToScreen` represents your app's logging function.

```cpp theme={null}
HRESULT hr = XblEventsWriteInGameEvent(
    xboxLiveContext,
    "PuzzleSolved",
    R"({"DifficultyLevelId":100, "GameplayModeId":"Adventure"})",
    R"({"LocationX":1,"LocationY":1})"
);
if (FAILED(hr))
{
    // Log the failure. Don't retry the call in a loop.
    LogToScreen("XblEventsWriteInGameEvent failed: 0x%08X", static_cast<unsigned int>(hr));
}
```

For more information, see [XblEventsWriteInGameEvent](https://docs.xbox.com/reference/live/xsapi-c/events_c/functions/xbleventswriteingameevent.md).

## Troubleshooting

* **The call returns `E_INVALIDARG`.** *xboxLiveContext* or the event name is null.
* **The call returns `E_XBL_NOT_INITIALIZED`.** Call `XblInitialize` before you write events.
* **The call returns `E_NOTIMPL`.** The XGameEvent feature of the Gaming Runtime isn't available. On a Windows PC, the installed Gaming Runtime Services must include the XGameEvent feature.
* **The call succeeds, but the stat or achievement doesn't change.** The event name and the names of the event fields must match the names in your title's service configuration. Names are case-insensitive. If the event name doesn't match an event in the service configuration, the service drops the event without notifying your game.
* **Field values are in the wrong place.** Put fields that have a finite set of numeric or string values, such as difficulty level or game mode, in the dimensions. Put scalar numeric metrics, such as score, time, or position, in the measurements.
* **Updates take time.** Events are written locally on the device, even when the device is offline, and are uploaded when the device is online. If the device is online, event-based stats typically update 5 to 20 seconds after the event is written.


## Related topics

- [Event-based achievements example code (contents)](https://docs.xbox.com/services/xbox-services/player-data/achievements/event-based/how-to/live-achievements-eb-howto-nav.md)
- [XBOX Achievements Manager API overview](https://docs.xbox.com/services/xbox-services/player-data/achievements/achievements-manager/live-achievements-manager-overview.md)
- [Writing an event to power an event-based stat](https://docs.xbox.com/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-sending-eb-stat.md)
- [Overview of event-based Achievements](https://docs.xbox.com/services/xbox-services/player-data/achievements/event-based/live-achievements-eb-overview.md)
- [Portal configuration of event-based Achievements](https://docs.xbox.com/services/xbox-services/player-data/achievements/event-based/config/live-achievements-eb-portal.md)