# Changelog

All notable changes to the Kradle challenges SDK (`@kradle/challenges-sdk`) are
documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

<!--
This file is published: it ships inside the npm tarball as CHANGELOG.md. Write
only what a consumer of the published package can see and act on.

The entry for each release is drafted by the "Create Release PR" workflow (rules
in .github/changelog-prompt.md) and reviewed in the PR before merging. You can
also hand-edit this file or the [Unreleased] section at any time.
-->

## [Unreleased]

## [0.10.0] - 2026-07-17

### Changed

- `start_challenge` now performs all setup in a single tick. The separate `init_participants` function that ran one second later is removed; its handler (if defined) runs in the same tick, immediately after the `start_challenge` handler.
- The implicit inventory clear now runs before user events, so items given in `start_challenge` survive it.

### Deprecated

- `init_participants` event. Use `start_challenge` instead. Using `init_participants` logs a build-time deprecation warning.

### Fixed

- `.end_condition()` now defers callback evaluation to `build()`, fixing the documented bridge pattern where a variable captured from an event handler was always `undefined` at chain time.
- **Breaking:** `.end_condition()` callbacks that return `undefined` now throw at build time instead of silently falling back to the tick-limit end condition. Either omit `.end_condition()` entirely or return a `ConditionType`.
- `LLM_README.md` now documents that the `.end_condition()` callback must return a `ConditionType`.

## [0.9.0] - 2026-07-16

### Removed

- **Breaking:** Removed `Actions.custom`. The wrapper was a no-op — any Sandstone code written inside it works identically when written directly in the handler. Replace `Actions.custom(() => { ... })` with the callback body.

## [0.8.1] - 2026-07-13

### Changed

- Internal maintenance release.

## [0.8.0] - 2026-07-10

### Changed

- `CHANGELOG.md` is now included in the npm package so `kradle update-sdk` can fetch it per version and show the migration delta before bumping. Breaking entries use a `**Breaking:**` prefix that the CLI highlights automatically.

## [0.7.2] - 2026-07-09

### Changed

- The datapack output path is now resolved from the `KRADLE_CHALLENGES_PATH` environment variable (falling back to a default for standalone use) instead of from the `kradle_challenge_path` config field. Previously a hardcoded config value could silently redirect the build away from where the CLI packages it, shipping a stale datapack.

### Deprecated

- `kradle_challenge_path` config field. The value is now ignored; passing it emits a `console.warn` advising removal.

### Fixed

- `LLM_README.md` corrected the `Actions.setTime` signature (was documented as accepting a tick number when the source only accepts `"day"` or `"night"`).
- `LLM_README.md` now documents twelve previously undocumented Actions: `assignRandomTag`, `custom`, `setGamemode`, `eliminate`, `isStandingOn`, `giveAll`, `randomInt`, `maxPlayerScore`, `detectBlockMissing`, `summonEntityWithStats`, `countEntities`, and `flatArena`.

## [0.6.2] - 2026-06-23

### Added

- `Actions.forceMoveTo` forces target player(s) to interrupt their running code and walk to absolute coordinates. Accepts `"self"` when called from a per-player context (e.g. inside `forEveryPlayer`); a contextless `forceMoveTo("self")` is caught by the CLI's context-safety check.

### Changed

- `mapTarget` now throws on any raw `@...` selector string (e.g. `"@s"`, `"@a"`). Use `"self"`, a role name, or a `Selector` object instead. Previously `"@s"` silently produced a selector matching nobody.

### Fixed

- Individual custom-event handlers (per-player score and advancement events) now run `at @s` as well as `as @s`. Previously relative coordinates (`~ ~ ~`) and `distance=` selectors inside the handler resolved from world spawn instead of the triggering player.

## [0.6.1] - 2026-06-09

### Added

- Voting primitives (`votedFor`, `promptVote`, `allVotesIn`, `assignDefaultVotes`) for challenges that use discuss-then-vote-then-act phases as an alternative to pad-based voting.
- Build-time validation of vote IDs and options against `KRADLE_CHALLENGE_VOTING_OPTIONS` (when set), matching the existing `getLocation`/`setEndState` pattern. `promptVote` also validates each announced option against the declared `votingOptions`.

[Unreleased]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.10.0...HEAD
[0.10.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.9.0...v0.10.0
[0.9.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.8.1...v0.9.0
[0.8.1]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.8.0...v0.8.1
[0.8.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.7.2...v0.8.0
[0.7.2]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.6.2...v0.7.2
[0.6.2]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.6.1...v0.6.2
[0.6.1]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.6.0...v0.6.1