{"id":15398632,"url":"https://github.com/seven-mile/scripthookwar3","last_synced_at":"2025-04-15T22:31:11.812Z","repository":{"id":65686588,"uuid":"452567010","full_name":"seven-mile/ScriptHookWar3","owner":"seven-mile","description":"Another ASI Plugin for WC3, to execute jass written in C++ at runtime!","archived":false,"fork":false,"pushed_at":"2022-03-21T06:02:11.000Z","size":125,"stargazers_count":14,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T03:41:58.864Z","etag":null,"topics":["jass","reverse-engineering","warcraft3"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seven-mile.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-27T06:33:25.000Z","updated_at":"2024-12-14T09:35:27.000Z","dependencies_parsed_at":"2023-02-04T11:25:11.517Z","dependency_job_id":null,"html_url":"https://github.com/seven-mile/ScriptHookWar3","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-mile%2FScriptHookWar3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-mile%2FScriptHookWar3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-mile%2FScriptHookWar3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seven-mile%2FScriptHookWar3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seven-mile","download_url":"https://codeload.github.com/seven-mile/ScriptHookWar3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249166006,"owners_count":21223361,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jass","reverse-engineering","warcraft3"],"created_at":"2024-10-01T15:44:57.751Z","updated_at":"2025-04-15T22:31:11.399Z","avatar_url":"https://github.com/seven-mile.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ScriptHookWar3\n\n### Install\n\nThis is an **ASI Plugin**! You need to install an ASI Loader first, and put the output `ScriptHookWar3.asi` in a proper directory to load it.\n\n### Usage\n\n#### Use NativeTrainer Directly\n\nI've implemented a NativeTrainer, which is similar to HKE script.\n\nTo open trainer main menu, just press F5. And you can easily understand how to enable features in it.\n\nTo make a building that you are constructing complete right now, press arrow left key (\u003c-).\n\nThat's all, enjoy!\n\n#### Calling Jass Native Functions\n\nWith the C++ template, ScriptHookWar3 provides a graceful way to call native jass functions:\n\n```cpp\nconst int PLAYERID_LOCAL = 0;\nauto ply = CallFn\u003cJassPlayer\u003e(\"Player\", PLAYERID_LOCAL);\nauto grp = CallFn\u003cJassGroup\u003e(\"CreateGroup\");\nCallFn\u003cvoid\u003e(\"GroupEnumUnitsSelected\", grp, ply, false);\nauto unit = CallFn\u003cJassUnit\u003e(\"FirstOfGroup\", grp);\nconst int UNIT_TYPE_HERO = 0;\nif (CallFn\u003cbool\u003e(\"IsUnitType\", unit, UNIT_TYPE_HERO)) {\n  CallFn\u003cvoid\u003e(\"AddHeroXP\", unit, 1000, true);\n\n  CallFn\u003cvoid\u003e(\n    \"DisplayTimedTextToPlayer\",\n    CallFn\u003cJassPlayer\u003e(\"Player\", 0),\n    0.0f,\n    0.0f,\n    10.0f,\n    \"ScriptHookWar3: Added!\"\n  );\n} else {\n  CallFn\u003cvoid\u003e(\n    \"DisplayTimedTextToPlayer\",\n    CallFn\u003cJassPlayer\u003e(\"Player\", 0),\n    0.0f,\n    0.0f,\n    10.0f,\n    \"ScriptHookWar3: The selected unit is not hero.\"\n  );\n}\n\n\n```\n\n#### Function Callback\n\n1.28 update: **C++ Callback is supported!**\n\n```cpp\nauto trg = CallFn\u003cJassTrigger\u003e(\"CreateTrigger\");\nauto act = CallFn\u003cJassTriggerAction\u003e(\"TriggerAddAction\", trg, []() {\n  DebugOutput(\"ScriptHookWar3: Action triggered!\");\n});\nCallFn\u003cJassEvent\u003e(\"TriggerRegisterPlayerChatEvent\", trg, ply, \"war\", true);\n```\n\nYes, just pass lambda and it will work!\n\nOh, you don't need callback arguments, since you already have lambda capturing.\n\n#### C++ OOP Wrapper\n\nI wrote some class wrapper for Jass objects, so that you can use\n\n```cpp\nauto ply = JassPlayer::LocalPlayer();\nif (JassHero hero = ply.GetSelectedUnits().FirstUnit()) {\n  hero.SetMoveSpeed(2 * hero.GetMoveSpeed());\n} else {\n  DebugOutput(\"oops, it is NOT a HERO.\");\n}\n```\n\n#### Menu Creator API\n\nIt's an extremely powerful shortcut for game menu creation.\n\nThe so-called menu is based on game-native dialog and supports ordinary action buttons, switch buttons and navigation between menus.\n\nFor example, to create a menu structure like:\n\n```\nResource\n-- Add Money\n-- Add Lumber\n\nSelected Unit\n-- Scale up / Scale down (change its text and behavior after clicked)\n```\n\nWe can simply write\n\n```cpp\n// define your menus\nstatic ScriptMenu mainMenu, resMenu, unitMenu;\n\n// define main menu layout, there're two submenus\nmainMenu.AddSubMenuButton(\"Resource\", resMenu);\nmainMenu.AddSubMenuButton(\"Selected Unit\", unitMenu);\n// this button exit the menu\nmainMenu.AddActionButton(\"Exit Menu\", [](){});\n\n// define two action buttons\nresMenu.AddActionButton(\"Add Money\", []() {\n    // It's simple, right? I love it.\n    auto ply = JassPlayer::LocalPlayer();\n    ply.SetState(PLAYER_STATE::RESOURCE_GOLD,\n        ply.GetState(PLAYER_STATE::RESOURCE_GOLD) + 9999);\n});\nresMenu.AddActionButton(\"Add Lumber\", []() {\n    auto ply = JassPlayer::LocalPlayer();\n    ply.SetState(PLAYER_STATE::RESOURCE_LUMBER,\n        ply.GetState(PLAYER_STATE::RESOURCE_LUMBER) + 9999);\n});\n// this button return to the previous level\nresMenu.AddSubMenuButton(\"Return\", mainMenu);\nresMenu.AddActionButton(\"Exit Menu\", [](){});\n\nunitMenu.AddSwitchButton(\"Scale Down\", \"Scale Up\",\n[]() {\n    auto unit = JassPlayer::LocalPlayer().GetSelectedUnits().FirstUnit();\n    unit.SetScale(1.0);\n},\n[]() {\n    auto unit = JassPlayer::LocalPlayer().GetSelectedUnits().FirstUnit();\n    unit.SetScale(2.0);\n});\nunitMenu.AddSubMenuButton(\"Return\", mainMenu);\nunitMenu.AddActionButton(\"Exit Menu\", []() {});\n```\n\n### Game Version\n\nWe only support 1.20e by now. But it's easy to adapt other versions if you just need `CallFn\u003cRetTy\u003e`(2 offsets to find: the timer code and the native function pool). The native function pool structure turns into a BST for 1.3+, which needs some extra efforts.\n\nAnyway, I'm focusing on exploring more features rather than support more versions stably. Higher versions will come, but not now I think.\n\n### Coming Refactor\n\nI will refactor the code recently. The structure is kind of confusing, and performance optimization is also needed.\n\n2.7 update: I will probably update this project to C++ 20 Module architecture ;)\n\n### Todo\n\nNow I'm working on providing **C++ function callback binding**. Then you can pass C++ function pointer to a function taking `code`-typed arguments, like `TriggerAddAction`, which provides important event system!\n\nAfter that, I'm considering write a wrapper for `Dialog`. And maybe OOP wrapper for more jass types, if I'd love to.\n\n1.28 update: They are close to a finish. Now I will try to build a NativeTrainer, which providing similar interface to HKE script inject. But this time the injection happens at runtime and we don't need to modify the map.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseven-mile%2Fscripthookwar3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseven-mile%2Fscripthookwar3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseven-mile%2Fscripthookwar3/lists"}