dfhack-remote-node 2.0.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "dfhack-remote-node",
+  "version": "2.0.0",
+  "description": "Node client for the DFHack Remote RPC protocol (protobuf over TCP)",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "build/proto.json",
+    "proto",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "npm run gen-proto && tsup",
+    "gen-proto": "pbjs proto/*.proto -t json -o build/proto.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "test": "node scripts/mock-server-test.js",
+    "spike": "node scripts/m0-spike.js",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "dwarf",
+    "fortress",
+    "dfhack",
+    "remote",
+    "RemoteFortressReader"
+  ],
+  "author": "Alexander Olvera",
+  "license": "ISC",
+  "dependencies": {
+    "protobufjs": "^7.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "prettier": "^3.0.0",
+    "protobufjs-cli": "^1.1.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexanderolvera/dfhack-remote-node.git"
+  },
+  "homepage": "https://github.com/alexanderolvera/dfhack-remote-node#readme",
+  "bugs": {
+    "url": "https://github.com/alexanderolvera/dfhack-remote-node/issues"
+  }
+}

package/proto/AdventureControl.proto

@@ -0,0 +1,109 @@
+syntax = "proto2";
+
+//Attempts to provide a complete framework for reading everything from a fortress needed for vizualization
+package AdventureControl;
+
+option optimize_for = LITE_RUNTIME;
+
+import "RemoteFortressReader.proto";
+
+// Plugin: RemoteFortressReader
+
+enum AdvmodeMenu
+{
+    Default = 0;
+    Look = 1;
+    ConversationAddress = 2;
+    ConversationSelect = 3;
+    ConversationSpeak = 4;
+    Inventory = 5;
+    Drop = 6;
+    ThrowItem = 7;
+    Wear = 8;
+    Remove = 9;
+    Interact = 10;
+    Put = 11;
+    PutContainer = 12;
+    Eat = 13;
+    ThrowAim = 14;
+    Fire = 15;
+    Get = 16;
+    Unk17 = 17;
+    CombatPrefs = 18;
+    Companions = 19;
+    MovementPrefs = 20;
+    SpeedPrefs = 21;
+    InteractAction = 22;
+    MoveCarefully = 23;
+    Announcements = 24;
+    UseBuilding = 25;
+    Travel = 26;
+    Unk27 = 27;
+    Unk28 = 28;
+    SleepConfirm = 29;
+    SelectInteractionTarget = 30;
+    Unk31 = 31;
+    Unk32 = 32;
+    FallAction = 33;
+    ViewTracks = 34;
+    Jump = 35;
+    Unk36 = 36;
+    AttackConfirm = 37;
+    AttackType = 38;
+    AttackBodypart = 39;
+    AttackStrike = 40;
+    Unk41 = 41;
+    Unk42 = 42;
+    DodgeDirection = 43;
+    Unk44 = 44;
+    Unk45 = 45;
+    Build = 46;
+}
+
+enum CarefulMovementType
+{
+    DEFAULT_MOVEMENT = 0;
+    RELEASE_ITEM_HOLD = 1;
+    RELEASE_TILE_HOLD = 2;
+    ATTACK_CREATURE = 3;
+    HOLD_TILE = 4;
+    MOVE = 5;
+    CLIMB = 6;
+    HOLD_ITEM = 7;
+    BUILDING_INTERACT = 8;
+    ITEM_INTERACT = 9;
+    ITEM_INTERACT_GUIDE = 10;
+    ITEM_INTERACT_RIDE = 11;
+    ITEM_INTERACT_PUSH = 12;
+}
+
+enum MiscMoveType
+{
+    SET_CLIMB = 0;
+    SET_STAND = 1;
+    SET_CANCEL = 2;
+}
+
+message MoveCommandParams
+{
+    optional RemoteFortressReader.Coord direction = 1;
+}
+
+message MovementOption
+{
+    optional RemoteFortressReader.Coord dest = 1;
+    optional RemoteFortressReader.Coord source = 2;
+    optional RemoteFortressReader.Coord grab = 3;
+    optional CarefulMovementType movement_type = 4;
+}
+
+message MenuContents
+{
+    optional AdvmodeMenu current_menu = 1;
+    repeated MovementOption movements = 2;
+}
+
+message MiscMoveParams
+{
+    optional MiscMoveType type = 1;
+}

package/proto/Basic.proto

@@ -0,0 +1,207 @@
+syntax = "proto2";
+
+package dfproto;
+
+option optimize_for = LITE_RUNTIME;
+
+message EnumItemName {
+    required int32 value = 1;
+    optional string name = 2;
+
+    // For bitfield members
+    optional int32 bit_size = 3 [default = 1];
+};
+
+message BasicMaterialId {
+    required int32 type = 1;
+    required sint32 index = 2;
+};
+
+message BasicMaterialInfo {
+    required int32 type = 1;
+    required sint32 index = 2;
+
+    // The raw token
+    required string token = 3;
+
+    // IF mask.flags:
+    // List of material_flags indices
+    repeated int32 flags = 4;
+
+    // Material type/index expanded:
+    optional int32 subtype = 5 [default = -1];
+    optional int32 creature_id = 6 [default = -1];
+    optional int32 plant_id = 7 [default = -1];
+    optional int32 histfig_id = 8 [default = -1];
+
+    optional string name_prefix = 9 [default = ""];
+
+    // IF mask.states: in listed order;
+    // ELSE: one state matching mask.temperature
+    repeated fixed32 state_color = 10;
+    repeated string state_name = 11;
+    repeated string state_adj = 12;
+
+    // IF mask.reaction:
+    message Product {
+        required string id = 1;
+        required int32 type = 2;
+        required sint32 index = 3;
+    };
+    repeated string reaction_class = 13;
+    repeated Product reaction_product = 14;
+
+    // IF mask.flags:
+    repeated int32 inorganic_flags = 15;
+};
+
+message BasicMaterialInfoMask {
+    enum StateType {
+        Solid = 0;
+        Liquid = 1;
+        Gas = 2;
+        Powder = 3;
+        Paste = 4;
+        Pressed = 5;
+    };
+    repeated StateType states = 1;
+    optional int32 temperature = 4 [default = 10015];
+
+    optional bool flags = 2 [default = false];
+    optional bool reaction = 3 [default = false];
+};
+
+message JobSkillAttr {
+    required int32 id = 1;
+    required string key = 2;
+
+    optional string caption = 3;
+    optional string caption_noun = 4;
+
+    optional int32 profession = 5;
+    optional int32 labor = 6;
+    optional string type = 7;
+};
+
+message ProfessionAttr {
+    required int32 id = 1;
+    required string key = 2;
+
+    optional string caption = 3;
+    optional bool military = 4;
+    optional bool can_assign_labor = 5;
+
+    optional int32 parent = 6;
+};
+
+message UnitLaborAttr {
+    required int32 id = 1;
+    required string key = 2;
+
+    optional string caption = 3;
+};
+
+message NameInfo {
+    optional string first_name = 1;
+    optional string nickname = 2;
+
+    optional int32 language_id = 3 [default = -1];
+
+    optional string last_name = 4;
+    optional string english_name = 5;
+};
+
+message NameTriple {
+    required string normal = 1;
+    optional string plural = 2;
+    optional string adjective = 3;
+};
+
+message UnitCurseInfo {
+    required fixed32 add_tags1 = 1;
+    required fixed32 rem_tags1 = 2;
+    required fixed32 add_tags2 = 3;
+    required fixed32 rem_tags2 = 4;
+
+    optional NameTriple name = 5;
+};
+
+message SkillInfo {
+    required int32 id = 1;
+    required int32 level = 2;
+    required int32 experience = 3;
+};
+
+message UnitMiscTrait {
+    required int32 id = 1;
+    required int32 value = 2;
+};
+
+message BasicUnitInfo {
+    required int32 unit_id = 1;
+
+    required int32 pos_x = 13;
+    required int32 pos_y = 14;
+    required int32 pos_z = 15;
+
+    optional NameInfo name = 2;
+
+    required fixed32 flags1 = 3;
+    required fixed32 flags2 = 4;
+    required fixed32 flags3 = 5;
+
+    required int32 race = 6;
+    required int32 caste = 7;
+    optional int32 gender = 8 [default = -1];
+
+    optional int32 civ_id = 9 [default = -1];
+    optional int32 histfig_id = 10 [default = -1];
+
+    optional int32 death_id = 17 [default = -1];
+    optional uint32 death_flags = 18;
+
+    // IF mask.profession:
+    optional int32 squad_id = 19 [default = -1];
+    optional int32 squad_position = 20 [default = -1];
+
+    optional int32 profession = 22 [default = -1];
+    optional string custom_profession = 23;
+
+    // IF mask.labors:
+    repeated int32 labors = 11;
+
+    // IF mask.skills:
+    repeated SkillInfo skills = 12;
+
+    // IF mask.misc_traits:
+    repeated UnitMiscTrait misc_traits = 24;
+
+    optional UnitCurseInfo curse = 16;
+
+    repeated int32 burrows = 21;
+};
+
+message BasicUnitInfoMask {
+    optional bool labors = 1 [default = false];
+    optional bool skills = 2 [default = false];
+    optional bool profession = 3 [default = false];
+    optional bool misc_traits = 4 [default = false];
+};
+
+message BasicSquadInfo {
+    required int32 squad_id = 1;
+
+    optional NameInfo name = 2;
+
+    // A special field completely overriding the name:
+    optional string alias = 3;
+
+    // Member histfig ids:
+    repeated sint32 members = 4;
+};
+
+message UnitLaborState {
+    required int32 unit_id = 1;
+    required int32 labor = 2;
+    required bool value = 3;
+};

package/proto/BasicApi.proto

@@ -0,0 +1,109 @@
+syntax = "proto2";
+
+package dfproto;
+
+option optimize_for = LITE_RUNTIME;
+
+import "Basic.proto";
+
+// RPC GetVersion : EmptyMessage -> StringMessage
+// RPC GetDFVersion : EmptyMessage -> StringMessage
+
+// RPC GetWorldInfo : EmptyMessage -> GetWorldInfoOut
+message GetWorldInfoOut {
+    enum Mode {
+        MODE_DWARF = 1;
+        MODE_ADVENTURE = 2;
+        MODE_LEGENDS = 3;
+    };
+    required Mode mode = 1;
+
+    required string save_dir = 2;
+    optional NameInfo world_name = 3;
+
+    // Dwarf mode
+    optional int32 civ_id = 4;
+    optional int32 site_id = 5;
+    optional int32 group_id = 6;
+    optional int32 race_id = 7;
+
+    // Adventure mode
+    optional int32 player_unit_id = 8;
+    optional int32 player_histfig_id = 9;
+    repeated int32 companion_histfig_ids = 10;
+};
+
+// RPC ListEnums : EmptyMessage -> ListEnumsOut
+message ListEnumsOut {
+    repeated EnumItemName material_flags = 1;
+    repeated EnumItemName inorganic_flags = 2;
+
+    repeated EnumItemName unit_flags1 = 3;
+    repeated EnumItemName unit_flags2 = 4;
+    repeated EnumItemName unit_flags3 = 5;
+
+    repeated EnumItemName unit_labor = 6;
+    repeated EnumItemName job_skill = 7;
+
+    repeated EnumItemName cie_add_tag_mask1 = 8;
+    repeated EnumItemName cie_add_tag_mask2 = 9;
+
+    repeated EnumItemName death_info_flags = 10;
+
+    repeated EnumItemName profession = 11;
+};
+
+// RPC ListJobSkills : EmptyMessage -> ListJobSkillsOut
+message ListJobSkillsOut {
+    repeated JobSkillAttr skill = 1;
+    repeated ProfessionAttr profession = 2;
+    repeated UnitLaborAttr labor = 3;
+};
+
+// RPC ListMaterials : ListMaterialsIn -> ListMaterialsOut
+message ListMaterialsIn {
+    optional BasicMaterialInfoMask mask = 1;
+
+    // Specific materials:
+    repeated BasicMaterialId id_list = 2;
+
+    // Complete list by type:
+    optional bool builtin = 3;
+    optional bool inorganic = 4;
+    optional bool creatures = 5;
+    optional bool plants = 6;
+};
+message ListMaterialsOut {
+    repeated BasicMaterialInfo value = 1;
+};
+
+// RPC ListUnits : ListUnitsIn -> ListUnitsOut
+message ListUnitsIn {
+    optional BasicUnitInfoMask mask = 1;
+
+    // Specific units:
+    repeated int32 id_list = 2;
+
+    // All units matching:
+    optional bool scan_all = 5;
+
+    optional int32 race = 3;
+    optional int32 civ_id = 4;
+    optional bool dead = 6; // i.e. passive corpse
+    optional bool alive = 7; // i.e. not dead or undead
+    optional bool sane = 8; // not dead, ghost, zombie, or insane
+};
+message ListUnitsOut {
+    repeated BasicUnitInfo value = 1;
+};
+
+// RPC ListSquads : ListSquadsIn -> ListSquadsOut
+message ListSquadsIn {}
+message ListSquadsOut {
+    repeated BasicSquadInfo value = 1;
+};
+
+// RPC SetUnitLabors : SetUnitLaborsIn -> EmptyMessage
+message SetUnitLaborsIn {
+    repeated UnitLaborState change = 1;
+};

package/proto/CoreProtocol.proto

@@ -0,0 +1,92 @@
+syntax = "proto2";
+
+package dfproto;
+
+option optimize_for = LITE_RUNTIME;
+
+message CoreTextFragment {
+    required string text = 1;
+
+    enum Color {
+        COLOR_BLACK = 0;
+        COLOR_BLUE = 1;
+        COLOR_GREEN = 2;
+        COLOR_CYAN = 3;
+        COLOR_RED = 4;
+        COLOR_MAGENTA = 5;
+        COLOR_BROWN = 6;
+        COLOR_GREY = 7;
+        COLOR_DARKGREY = 8;
+        COLOR_LIGHTBLUE = 9;
+        COLOR_LIGHTGREEN = 10;
+        COLOR_LIGHTCYAN = 11;
+        COLOR_LIGHTRED = 12;
+        COLOR_LIGHTMAGENTA = 13;
+        COLOR_YELLOW = 14;
+        COLOR_WHITE = 15;
+    };
+    optional Color color = 2;
+}
+
+message CoreTextNotification {
+    repeated CoreTextFragment fragments = 1;
+}
+
+message CoreErrorNotification {
+    enum ErrorCode {
+        CR_LINK_FAILURE = -3;
+        CR_WOULD_BREAK = -2;
+        CR_NOT_IMPLEMENTED = -1;
+        CR_OK = 0;
+        CR_FAILURE = 1;
+        CR_WRONG_USAGE = 2;
+        CR_NOT_FOUND = 3;
+    };
+
+    required ErrorCode code = 1;
+}
+
+message EmptyMessage {}
+
+message IntMessage {
+    required int32 value = 1;
+}
+
+message IntListMessage {
+    repeated int32 value = 1;
+}
+
+message StringMessage {
+    required string value = 1;
+}
+
+message StringListMessage {
+    repeated string value = 1;
+}
+
+// RPC BindMethod : CoreBindRequest -> CoreBindReply
+message CoreBindRequest {
+    required string method = 1;
+    required string input_msg = 2;
+    required string output_msg = 3;
+    optional string plugin = 4;
+}
+message CoreBindReply {
+    required int32 assigned_id = 1;
+}
+
+// RPC RunCommand : CoreRunCommandRequest -> EmptyMessage
+message CoreRunCommandRequest {
+    required string command = 1;
+    repeated string arguments = 2;
+}
+
+// RPC CoreSuspend : EmptyMessage -> IntMessage
+// RPC CoreResume : EmptyMessage -> IntMessage
+
+// RPC RunLua : CoreRunLuaRequest -> StringListMessage
+message CoreRunLuaRequest {
+    required string module = 1;
+    required string function = 2;
+    repeated string arguments = 3;
+}

package/proto/DwarfControl.proto

@@ -0,0 +1,97 @@
+syntax = "proto2";
+
+//Attempts to provide a complete framework for reading everything from a fortress needed for vizualization
+package DwarfControl;
+
+option optimize_for = LITE_RUNTIME;
+
+// Plugin: RemoteFortressReader
+
+import "ui_sidebar_mode.proto";
+import "RemoteFortressReader.proto";
+
+// RPC GetSideMenu : EmptyMessage -> SidebarState
+// RPC SetSideMenu : SidebarCommand -> EmptyMessage
+
+
+enum BuildCategory
+{
+    NotCategory = 0;
+    SiegeEngines = 1;
+    Traps = 2;
+    Workshops = 3;
+    Furnaces = 4;
+    Constructions = 5;
+    MachineComponents = 6;
+    Track = 7;
+}
+
+enum MenuAction
+{
+    MenuNone = 0;
+    MenuSelect = 1;
+    MenuCancel = 2;
+    MenuSelectAll = 3;
+}
+
+enum BuildSelectorStage
+{
+    StageNoMat = 0;
+    StagePlace = 1;
+    StageItemSelect = 2;
+}
+
+message SidebarState
+{
+    optional proto.enums.ui_sidebar_mode.ui_sidebar_mode mode = 1;
+    repeated MenuItem menu_items = 2;
+    optional BuildSelector build_selector = 3;
+}
+
+message MenuItem
+{
+    optional RemoteFortressReader.BuildingType building_type = 1;
+    optional int32 existing_count = 2;
+    optional BuildCategory build_category = 3;
+}
+
+message SidebarCommand
+{
+    optional proto.enums.ui_sidebar_mode.ui_sidebar_mode mode = 1;
+    optional int32 menu_index = 2;
+    optional MenuAction action = 3;
+    optional RemoteFortressReader.Coord selection_coord = 4;
+}
+
+message BuiildReqChoice
+{
+    optional int32 distance = 1;
+    optional string name = 2;
+    optional int32 num_candidates = 3;
+    optional int32 used_count = 4;
+}
+
+message BuildItemReq
+{
+    //Put filter here = 1
+    optional int32 count_required = 2;
+    optional int32 count_max = 3;
+    optional int32 count_provided = 4;
+}
+
+message BuildSelector
+{
+    optional RemoteFortressReader.BuildingType building_type = 1;
+    optional BuildSelectorStage stage = 2;
+    repeated BuiildReqChoice choices = 3;
+    optional int32 sel_index = 4;
+    repeated BuildItemReq requirements = 5;
+    optional int32 req_index = 6;
+    repeated string errors = 7;
+    optional int32 radius_x_low = 8;
+    optional int32 radius_y_low = 9;
+    optional int32 radius_x_high = 10;
+    optional int32 radius_y_high = 11;
+    optional RemoteFortressReader.Coord cursor = 12;
+    repeated int32 tiles = 13;
+}