@rbxts/htn-shop 1.0.1

package/README.md

@@ -0,0 +1,29 @@
+# @rbxts/shop
+
+ a simple HTN, SHOP-like planner written in js, based on [Pyhop](https://bitbucket.org/dananau/pyhop)
+
+ shop was easy to implement (less than 50 lines of code), and if you understand the basic ideas of HTN planning ([this presentation](http://www.cs.umd.edu/~nau/papers/nau2013game.pdf) contains a quick summary), shop should be easy to understand.
+
+ shop's planning algorithm is like the one in SHOP, but with several differences that should make it easier to integrate it with ordinary computer programs:
+
+ shop represents states of the world using ordinary variable bindings, not logical propositions. A state is just a js object. For example, you might write s.loc['v'] = 'd' to say that vehicle v is at location d in state s.
+
+ To write HTN operators and methods forjshop, you don't need to learn a specialized planning language. Instead, you write them as ordinary js functions. The current state (e.g., s in the above example) is passed to them as an argument.
+
+## Module Usage
+
+```
+npm install @rbxts/shop
+```
+
+see the unit.test.ts file for an example usage. more to follow.
+
+## Further reading
+
+ - Designing games mechanics with a HTN Planner - [PDF](http://www.gameaipro.com/GameAIPro/GameAIPro_Chapter12_Exploring_HTN_Planners_through_Example.pdf)
+
+ - Use in video games - [Youtube](https://youtu.be/kXm467TFTcY)
+
+## License
+
+MIT

package/out/index.d.ts

@@ -0,0 +1,2 @@
+import { Planner, State } from "./types";
+export declare function create<S extends State>(): Planner<S>;

package/out/init.luau

@@ -0,0 +1,87 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = require(game:GetService("ReplicatedStorage"):WaitForChild("rbxts_include"):WaitForChild("RuntimeLib"))
+local _util = TS.import(script, game:GetService("ReplicatedStorage"), "shop", "util")
+local extend = _util.extend
+local deepClone = _util.deepClone
+local tail = _util.tail
+local addOperators, setMethods, solve
+local function create()
+	local operators = {}
+	local taskMethods = {}
+	return {
+		operators = function(toAdd)
+			return addOperators(operators, toAdd)
+		end,
+		setMethods = function(taskName, methods)
+			return setMethods(taskMethods, taskName, methods)
+		end,
+		solve = function(state, tasks)
+			return solve(operators, taskMethods, state, tasks)
+		end,
+	}
+end
+function addOperators(currentOperators, toAdd)
+	extend(currentOperators, toAdd)
+end
+function setMethods(currentTaskMethods, taskName, toAdd)
+	currentTaskMethods[taskName] = toAdd
+end
+local seekPlan
+function solve(operators, taskMethods, state, tasks)
+	return seekPlan(operators, taskMethods, state, tasks, {}, 0)
+end
+function seekPlan(operators, taskMethods, state, tasks, plan, depth)
+	if #tasks == 0 then
+		return plan
+	end
+	local task1 = tasks[1]
+	local taskName = task1[1]
+	if operators[taskName] ~= nil then
+		local operator = operators[taskName]
+		local args = tail(task1)
+		local newstate = operator(deepClone(state), unpack(args))
+		if newstate then
+			local _exp = operators
+			local _exp_1 = taskMethods
+			local _exp_2 = tail(tasks)
+			local _array = {}
+			local _length = #_array
+			local _planLength = #plan
+			table.move(plan, 1, _planLength, _length + 1, _array)
+			_length += _planLength
+			_array[_length + 1] = task1
+			local solution = seekPlan(_exp, _exp_1, newstate, _exp_2, _array, depth + 1)
+			if solution ~= nil then
+				return solution
+			end
+		end
+	end
+	if taskMethods[taskName] ~= nil then
+		local solution = nil
+		for _, method in taskMethods[taskName] do
+			local args = tail(task1)
+			local subtasks = method(state, unpack(args))
+			if subtasks ~= nil then
+				local _exp = operators
+				local _exp_1 = taskMethods
+				local _exp_2 = state
+				local _array = {}
+				local _length = #_array
+				local _subtasksLength = #subtasks
+				table.move(subtasks, 1, _subtasksLength, _length + 1, _array)
+				_length += _subtasksLength
+				local _array_1 = tail(tasks)
+				table.move(_array_1, 1, #_array_1, _length + 1, _array)
+				solution = seekPlan(_exp, _exp_1, _exp_2, _array, plan, depth + 1)
+				if solution ~= nil then
+					break
+				end
+			end
+		end
+		return solution
+	end
+	return nil
+end
+return {
+	create = create,
+}

package/out/types.d.ts

@@ -0,0 +1,17 @@
+/** A task is represented as an array where the first element is the task name and the rest are arguments */
+export type Task = [string, ...defined[]];
+/** State can be any object with string keys */
+export type State = Record<string, defined>;
+/** An operator takes a state and task arguments, returns a new state or undefined if not applicable */
+export type Operator<S extends State> = (state: S, ...args: defined[]) => S | undefined;
+/** A method takes a state and task arguments, returns subtasks or undefined if not applicable */
+export type Method<S extends State> = (state: S, ...args: defined[]) => Task[] | undefined;
+/** Collection of operators keyed by task name */
+export type Operators<S extends State> = Record<string, Operator<S>>;
+/** Collection of methods for a task (multiple methods can apply to the same task) */
+export type TaskMethods<S extends State> = Record<string, Method<S>[]>;
+export interface Planner<S extends State> {
+    operators: (toAdd: Operators<S>) => void;
+    setMethods: (taskName: string, methods: Method<S>[]) => void;
+    solve: (state: S, tasks: Task[]) => Task[] | undefined;
+}

package/out/types.luau

@@ -0,0 +1,8 @@
+-- Compiled with roblox-ts v3.0.0
+--* A task is represented as an array where the first element is the task name and the rest are arguments 
+--* State can be any object with string keys 
+--* An operator takes a state and task arguments, returns a new state or undefined if not applicable 
+--* A method takes a state and task arguments, returns subtasks or undefined if not applicable 
+--* Collection of operators keyed by task name 
+--* Collection of methods for a task (multiple methods can apply to the same task) 
+return nil

package/out/util.d.ts

@@ -0,0 +1,3 @@
+export declare function deepClone<T>(obj: T): T;
+export declare function tail<T extends defined>(arr: T[]): T[];
+export declare function extend<T extends object>(target: T, source: T): T;

package/out/util.luau

@@ -0,0 +1,31 @@
+-- Compiled with roblox-ts v3.0.0
+local function deepClone(obj)
+	local _obj = obj
+	if typeof(_obj) ~= "table" then
+		return obj
+	end
+	local result = {}
+	for key, value in pairs(obj) do
+		result[key] = deepClone(value)
+	end
+	return result
+end
+local function tail(arr)
+	local result = {}
+	for i = 1, #arr - 1 do
+		local _arg0 = arr[i + 1]
+		table.insert(result, _arg0)
+	end
+	return result
+end
+local function extend(target, source)
+	for key, value in pairs(source) do
+		target[key] = value
+	end
+	return target
+end
+return {
+	deepClone = deepClone,
+	tail = tail,
+	extend = extend,
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@rbxts/htn-shop",
+	"version": "1.0.1",
+	"description": "a simple HTN SHOP-like planner",
+	"author": "shrjrd",
+	"license": "MIT",
+	"keywords": [
+		"planning",
+		"planner",
+		"shop",
+		"HTN"
+	],
+	"main": "out/init.lua",
+	"types": "out/index.d.ts",
+	"files": [
+		"out",
+		"!**/*.tsbuildinfo",
+		"!out/*.test.*",
+		"!out/jest.*"
+	],
+	"devDependencies": {
+		"@rbxts/compiler-types": "^3.0.0-types.0",
+		"@rbxts/jest": "^3.13.3-alpha.2",
+		"@rbxts/jest-globals": "^3.13.3-alpha.2",
+		"@rbxts/types": "^1.0.894",
+		"@typescript-eslint/eslint-plugin": "^8.48.0",
+		"@typescript-eslint/parser": "^8.48.0",
+		"eslint": "^9.39.1",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-prettier": "^5.5.4",
+		"eslint-plugin-roblox-ts": "^1.3.0",
+		"prettier": "^3.7.0",
+		"roblox-ts": "^3.0.0",
+		"rojo": "^1.0.3-rojo7.6.1",
+		"typescript": "^5.9.3"
+	},
+	"scripts": {
+		"build": "rbxtsc",
+		"build:dev": "rbxtsc --type game --rojo default.project.json",
+		"build:rbxl": "rojo sourcemap -o sourcemap.json && rojo build -o place.rbxl",
+		"watch": "npm run build:dev && npx concurrently \"npm run build:dev -- -w\" \"rojo serve\""
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/shrjrd/rbxts-htn-shop.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}