@kradle/challenges 0.0.1

package/src/constants.ts

@@ -0,0 +1,121 @@
+import { _, execute, Objective, type Score, Selector } from "sandstone";
+import { type _InputCustomEventType, type _InputVariableType, Actions } from "./types";
+import { getChildFunctionName } from "./utils";
+
+/**
+ * All possible events that can be defined in a challenge.
+ */
+export type POSSIBLE_SCENARIO_EVENTS = "start_challenge" | "init_participants" | "end_challenge" | "on_tick";
+
+export const VISIBLE_OBJECTIVE = Objective.create("kradle.board", "dummy", [{ text: "Kradle Board", color: "gold" }]);
+export const HIDDEN_OBJECTIVE = Objective.create("kradle.hidden");
+
+export const WATCHER = "watcher";
+export const WEB_VIEWER = "KradleWebViewer";
+export const KRADLE_PARTICIPANT_TAG = "kradle_participant";
+export const WINNER_TAG = "kradle_winner";
+export const DISPLAY_TAG = "***KRADLE***";
+
+export const MAX_DURATION = 5 * 60 * 20; // 5 minutes in ticks
+
+/// The selector that targets all participants in the game.
+export const ALL = Selector("@a", { tag: KRADLE_PARTICIPANT_TAG });
+export const GAME_STATES = {
+	CREATED: 0,
+	ON: 2,
+	OFF: 1,
+} as const;
+
+/// The variables that are builtin by default in every challenge.
+/// These variables are used to track the state of the game and the players.
+/// They can be used in the challenge definition to create end conditions, win conditions, and events.
+export const BUILTIN_VARIABLES = {
+	death_count: {
+		type: "individual",
+		objective_type: "deathCount",
+		default: 0,
+	},
+	has_never_died: {
+		type: "individual",
+		updater: (value: Score, { death_count }) => {
+			value.set(0);
+			_.if(death_count.equalTo(0), () => {
+				value.set(1);
+			});
+		},
+	},
+	alive_players: {
+		type: "global",
+		updater: (value: Score, { has_never_died }) => {
+			value.set(0);
+			execute.as(ALL).run(getChildFunctionName("alive_players"), () => {
+				_.if(has_never_died, () => {
+					value.add(1);
+				});
+			});
+		},
+	},
+	main_score: {
+		type: "individual",
+		default: 0,
+		updater: (value: Score) => {
+			VISIBLE_OBJECTIVE("@s").set(value);
+		},
+	},
+	game_timer: {
+		type: "global",
+		default: 0,
+		updater: (value: Score) => {
+			value.add(1);
+		},
+	},
+	game_state: {
+		type: "global",
+		default: GAME_STATES.CREATED,
+	},
+	player_count: {
+		type: "global",
+		default: 0,
+	},
+	/// This variable is used to assign a unique number to each player, starting from 1.
+	player_number: {
+		type: "individual",
+		objective_type: "dummy",
+		default: 0,
+		updater: (value: Score, { player_count }) => {
+			_.if(value.equalTo(0), () => {
+				player_count.add(1);
+				value.set(player_count);
+				//tellraw("@a", [`${DISPLAY_TAG}`, { selector: "@s" }, "@s is player number ", value]);
+			});
+		},
+	},
+	/// This variable is used to announce in-game deaths
+	death_event: {
+		type: "individual",
+		objective_type: "deathCount",
+		updater: (value: Score) => {
+			_.if(value.greaterThan(0), () => {
+				Actions.announce({
+					message: [Selector("@s"), " has died!"],
+				})();
+				value.set(0); // Reset the death count after announcing
+			});
+		},
+	},
+} satisfies Record<string, _InputVariableType<string>>;
+
+export type BUILTIN_VARIABLE_NAMES = keyof typeof BUILTIN_VARIABLES;
+
+export const BUILTIN_SCORE_EVENTS = (variables: Record<BUILTIN_VARIABLE_NAMES, Score>) =>
+	[
+		{
+			mode: "repeatable",
+			score: variables.main_score,
+			actions: [
+				() => {
+					VISIBLE_OBJECTIVE("@s").set(variables.main_score);
+				},
+			],
+		},
+	] satisfies _InputCustomEventType[];

package/src/index.ts

@@ -0,0 +1,4 @@
+export { Actions } from "./actions";
+export * from "./api_utils";
+export * from "./challenge";
+export * from "./constants";

package/src/testmode.ts

@@ -0,0 +1,18 @@
+import { raw, tag } from "sandstone";
+import { KRADLE_PARTICIPANT_TAG } from "./constants";
+
+//set to true to enable test mode
+export const test_mode_enabled = false;
+//set the minecraft name of the tester player
+const tester_minecraft_name = "";
+
+export const set_up_test_mode = () => {
+	// 1. Tag the tester player if they're going to be participating
+	tag(tester_minecraft_name).add(KRADLE_PARTICIPANT_TAG);
+
+	// 2. Set the tester player's gamemode, e.g. survival
+	raw(`gamemode survival ${tester_minecraft_name}`);
+
+	// 3. Set the gamerule sendCommandFeedback to true
+	raw("gamerule sendCommandFeedback true");
+};

package/src/types.ts

@@ -0,0 +1,136 @@
+import type { Score } from "sandstone";
+import type { OBJECTIVE_CRITERION } from "sandstone/arguments/generated";
+import type { AdvancementTriggers } from "sandstone/arguments/resources/AdvancementTriggers";
+import type { Action } from "./actions";
+import type { BUILTIN_VARIABLE_NAMES, POSSIBLE_SCENARIO_EVENTS } from "./constants";
+
+export { Actions } from "./actions";
+
+// Variables that are defined for a specific objective type will be stored in the scoreboard
+export type _SpecificObjectiveVariable<VARIABLE_NAMES extends string = string> = {
+	type: "individual";
+	objective_type: OBJECTIVE_CRITERION;
+	/** The default value for the variable. 0 if undefined. */
+	default?: number;
+	/** The updater function is used to dynamically compute the value of the variable. */
+	updater?: (value: Score, variables: Record<VARIABLE_NAMES, Score>) => void;
+};
+
+// Variables that do not specify an objective type are considered dummy variables.
+// If the are "global", they will be directly stored in the Visible or Hidden scoreboard.
+// Else, a specific objective will be created for them.
+export type _DummyGlobalVariable<VARIABLE_NAMES extends string = string> = {
+	type: "global";
+	/** Whether the value should be displayed in-game. */
+	hidden?: boolean;
+	/** The default value for the variable. 0 if undefined. */
+	default?: number;
+	/** The updater function is used to dynamically compute the value of the variable. */
+	updater?: (value: Score, variables: Record<VARIABLE_NAMES, Score>) => void;
+};
+
+export type _DummyIndividualVariable<VARIABLE_NAMES extends string = string> = {
+	type: "individual";
+	/** The default value for the variable. 0 if undefined. */
+	default?: number;
+	/** The updater function is used to dynamically compute the value of the variable. */
+	updater?: (value: Score, variables: Record<VARIABLE_NAMES, Score>) => void;
+};
+
+/**
+ * A custom variable defined for the whole challenge.
+ */
+export type _InputVariableType<VARIABLE_NAMES extends string = string> =
+	| _SpecificObjectiveVariable<VARIABLE_NAMES>
+	| _DummyGlobalVariable<VARIABLE_NAMES>
+	| _DummyIndividualVariable<VARIABLE_NAMES>;
+
+export function isSpecificObjectiveVariable(
+	variable: _InputVariableType<string>,
+): variable is _SpecificObjectiveVariable<string> {
+	return variable.type === "individual" && !!(variable as any).objective_type;
+}
+
+/**
+ * The base configuration necessary to define events, end conditions, and win conditions for a challenge.
+ */
+export type _BaseConfig<ROLE_NAMES extends string, VARIABLE_NAMES extends string> = {
+	/**
+	 * Name of the datapack that will be created for this challenge.
+	 */
+	name: string;
+
+	/**
+	 * The path where the datapack will be created. It is expected to be `kradle-studio/challenges`.
+	 */
+	kradle_challenge_path: string;
+
+	/**
+	 * Game duration in ticks.
+	 *
+	 * Can be set to `INFINITY` (the default) to run without a time limit.
+	 *
+	 * @default INFINITY
+	 */
+	GAME_DURATION?: number;
+	roles: ROLE_NAMES[];
+	custom_variables: Record<VARIABLE_NAMES, _InputVariableType<VARIABLE_NAMES | BUILTIN_VARIABLE_NAMES>>;
+};
+
+export type _ScenarioEvents = Partial<Record<POSSIBLE_SCENARIO_EVENTS, { actions: Action[] }>>;
+
+export type Roles<ROLES_NAMES extends string = string> = {
+	[role in ROLES_NAMES]: role;
+};
+
+export type FullVariable<VARIABLE_NAMES extends string = string> = {
+	type: "individual" | "global";
+	score: Score;
+	default: number | undefined;
+	updater: ((value: Score, variables: Record<VARIABLE_NAMES, Score>) => void) | undefined;
+};
+
+/**
+ * "Full" variables are the variables the challenges passes to the user in events/other variable updaters.
+ */
+export type FullVariables<VARIABLE_NAMES extends string = string> = Record<
+	VARIABLE_NAMES | BUILTIN_VARIABLE_NAMES,
+	FullVariable<VARIABLE_NAMES>
+>;
+
+export type Variables<VARIABLE_NAMES extends string = string> = Record<VARIABLE_NAMES | BUILTIN_VARIABLE_NAMES, Score>;
+
+type _InputEventCommonProperties = {
+	/** The target score to reach to trigger the event */
+	target?: number | undefined;
+	/** The mode of the event, either fire once or fire every time the score reaches the target */
+	mode: "fire_once" | "repeatable";
+	/** Actions to execute when the event is triggered */
+	actions: Action[];
+};
+
+export type _InputScoreCustomEventType = {
+	/** The target score to reach to trigger the event */
+	score: Score;
+} & _InputEventCommonProperties;
+
+export type _InputAdvancementCustomEventType = {
+	/** A list of criteria that must be met to trigger the event */
+	criteria: AdvancementTriggers[];
+} & _InputEventCommonProperties;
+
+export type _InputCustomEventType = _InputScoreCustomEventType | _InputAdvancementCustomEventType;
+
+export type CustomScoreEvent = {
+	/** The input event that defines the conditions for the custom event */
+	inputEvent: _InputScoreCustomEventType;
+
+	/** The score that counts how many times the event has been triggered */
+	counter: Score;
+
+	/** The type of the event */
+	type: "global" | "individual";
+
+	/** A name used for debugging purposes */
+	debugName: string;
+};

package/src/utils.ts

@@ -0,0 +1,22 @@
+import { dataPack } from "sandstone/init";
+
+/// This is stolen from "type-fest" library - this allows us to get autocomplete on the "string" type
+export type LiteralStringUnion<LiteralType> = LiteralType | (string & Record<never, never>);
+
+/**
+ * Generates a unique child function name based on the given name & the current context.
+ *
+ * For example, if you're inside a MCFunction named "test",
+ * getChildFunctionName("myFunction") will return "test/myFunction".
+ *
+ * This is useful to get meaningful names for child functions, instead of the standard "execute_as_1/2/3...".
+ *
+ * 👉 This brings more clarity to the generated functions tree, without impacting the datapack behavior.
+ *
+ * @param name The base name for the child function.
+ *
+ * @returns A meaningful child function name that is unique within the current context.
+ */
+export function getChildFunctionName(name: string): string {
+	return dataPack.getUniqueChildName(name).fullName;
+}

package/tsconfig.json

@@ -0,0 +1,38 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "./src",
+    "outDir": "./dist",
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "lib": [
+      "esnext"
+    ],
+    "types": [
+      "node"
+    ],
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    // Stricter Typechecking Options
+    // "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    // Style Options
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+    // Recommended Options
+    "strict": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}