/ThMouseX

A piece of software that enables mouse control in Touhou Project series.

Primary LanguageC++

ThMouseX

Introduction

ThMouseX is a fork from ThMouse made by hwei.

This is a tool that enables mouse control for Shoot 'em ups games, intended for Touhou Project series, allowing player character to move towards wherever the cursor points.

Demo clip: https://www.youtube.com/watch?v=uMkzmM13qpU

Download link

https://github.com/Meigyoku-Thmn/ThMouseX/releases
(Require .NET Framework 4.8 from version 2.1.0)

Differences of the fork

  • Support any game's resolutions
  • Support DirectX8, DirectX9 and DirectX11 games
  • Support .NET Framework games via NeoLua and Lib.Harmony
  • Can be opened and closed at any time, it will automatically detect configured games
  • You can use Lua script (Lua, LuaJIT, or NeoLua) to configure further.

Drawbacks

  • Only works with 32-bit games, if there is a good 64-bit bullet hell game I will consider adding 64-bit support.
  • Doesn't work well with Steam Overlay, although this is minimal.
  • Doesn't work well with other mods that inject their own overlay (for example, thprac), they can still work but the overlays will override each other.
  • Configuration is difficult.

Preconfigured games

This tool should be compatible with any Touhou games from 6 to the latest. Here is the list of preconfigured games in Games.txt:

  • Touhou 6   東方紅魔郷 ～ Embodiment of Scarlet Devil (v1.02h)
  • Touhou 7   東方妖々夢 ～ Perfect Cherry Blossom (v1.00b)
  • Touhou 8   東方永夜抄 ～ Imperishable Night (v1.00d)
  • Touhou 9   東方花映塚 ～ Phantasmagoria of Flower View (v1.50a)
  • Touhou 9.5   東方文花帖 ～ Shoot the Bullet (v1.02a)
  • Touhou 10  東方風神録 ～ Mountain of Faith (v1.00a)
  • Touhou 11  東方地霊殿 ～ Subterranean Animism (v1.00a)
  • Touhou 12  東方星蓮船 ～ Undefined Fantastic Object (v1.00b)
  • Touhou 12.5  Double Spoiler ～ 東方文花帖 (v1.00a)
  • Touhou 12.8  妖精大戦争 ～ 東方三月精 Fairy Wars (v1.00a)
  • Touhou 13  東方神霊廟 ～ Ten Desires (v1.00c)
  • Touhou 14  東方輝針城 ～ Double Dealing Character (v1.00b)
  • Touhou 14.3  弾幕アマノジャク ～ Impossible Spell Card (v1.00a)
  • Touhou 15  東方紺珠伝 ～ Legacy of Lunatic Kingdom (v1.00b)
  • Touhou 16  東方天空璋 ～ Hidden Star in Four Seasons (v1.00a)
  • Touhou 16.5  秘封ナイトメアダイアリー 〜 Violet Detector (v1.00a)
  • Touhou 17  東方鬼形獣 ～ Wily Beast and Weakest Creature (v1.00b)
  • Touhou 18  東方虹龍洞 ～ Unconnected Marketeerss (v1.00a)
  • Touhou 18.5  バレットフィリア達の闇市場 〜 100th Black Market (v1.00a)
  • Touhou 19  東方獣王園 〜 Unfinished Dream of All Living Ghost (v1.10c)

It also have preconfiguration of some other games:

You can add more games to Games2.txt and copy it to ThMouseX's directory, side-by-side with Games.txt.

FAQ

How to compile on your computer (not recommended for non-tech savvy)

This project can be compiled via Visual Studio (I use Visual Studio 2022), or just Visual Studio Build Tools:

Also you need .NET Framework 4.8 SDK.

You also need to setup vcpkg and put vcpkg folder path into the PATH of environment variables.

Remember to compile for 32-bit, toolset v143, .NET Framework 4.8, and make sure these files and folder are in the same folder:

  • ConfigScripts
  • 0Harmony.dll
  • Common.dll
  • Cursor.png
  • DX8Hook.dll
  • Games.txt
  • Neo.Lua.dll
  • NeoLuaBootstrap.dll
  • Sigil.dll
  • ThMCore.dll
  • THMouseX.exe
  • ThMouseX.txt
  • VirtualKeyCodes.txt

Another way to compile without installing anything on your computer (recommended way)

  • Fork the THMouseX repository to your Github account
    image
  • Go to the "Actions" tab
    image
  • Click "Deployment" on the left sidebar
    chrome_1lYLXTdT9o
  • Run the workflow
    chrome_AxRRzs1MUn
  • Wait for it, then download the produced zipped artifact (shown up in the page with url form https://github.com/<username>/ThMouseX/actions/runs/<flowid>)
    chrome_jdw1pXLJl2

How to use ThMouseX?

  1. Run ThMouseX.exe.
  2. Run your game, or you can run your game first and then run ThMouseX.exe.
  3. If the game is supported, a cursor will show upon entering the game.

How to control?

  • The character will move towards where the cursor points. Please note that it will NOT move immidiately with the cursor, because ThMouseX doesn't modifier any game's behavior.
  • You still have to use left hand to focus and shoot.
  • Left click to use bomb/spell.
  • Right click to toggle mouse control.
  • Press M to toggle Windows mouse cursor visibility.

How to close it?

  1. You can close your game first or ThMouseX first, it doesn't matter.
  2. Double-click the ThMouseX icon on the taskbar and press the Quit button, or right click it and press Exit.

Additional Instructions

Cursor sprite

The crosshair/cursor sprite may be changed:

  1. Find your preferred crosshair in .png format and place it into the same folder as ThMouseX.exe.
  2. Open up ThMouseX.txt.
  3. Change the file name after "CursorTexture = " to the preferred crosshair file's name. (Don't forget the file extension name ".png".)

Add your favorite games

You can extend ThMouseX to support more Shoot 'em ups games by modifying the "Games.txt" file. You can also use Lua script for advanced cases.

Sometime ThMouseX doesn't actually work, the game's character just keeps moving to a corner or is not bound exactly to the cursor

Try updating your game to the latest version. ThMouseX currently support only a single version of a game.

If it doesn't solve, then there are really rare bugs that I have yet found a way to fix.
Some workarounds:

  • Restart ThMouseX
  • Start ThMouseX FIRST, then start the game
  • When starting ThMouseX, make sure your game's window is NOT minimized (this should be fixed from version 2.1.0).

"Delay" movement, lag mouse cursor

This is a normal problem in every games that the in-game cursor is a little delay compared to the OS cursor. ThMouseX also doesn't change the game's behavior (it doesn't cheat), so the character still has to follow the game rule, no "teleportation".

Character cannot stay in one place where the cursor is, even when holding down the SHIFT button, the character just sways crazily around the cursor

The moving step of the character is a fixed value and usually longer than the mouse movement step you are able to make (for example, you can move the cursor 1 px, but the game character can't, if it moves, it has to move 5 px a frame). Holding SHIFT can reduce the moving step but only so much. I think this is an unsolvable issue.
But there is a case that the game character feel really lagged and sways a lot around the cursor however you try, I saw that in Touhou 7. Installing Vsync Patch does fix that.

Steam Overlay stops functioning, the game control is unusable too!

This is a limitation of how this tool hooks into the game's routine. Please avoid turning off ThMouseX while Steam Overlay is visible.

Game crashes when exiting or lauching ThMouseX

Please avoid lauching and exiting ThMouseX many times while the game is running.
So far I only see this bug on .NET Framework games and it's a rare bug. It may has something with the library Lib.Harmony which ThMouseX uses.

Antivirus programs' detection

This tool uses various code injection techniques, so it's normal that some antivirus programs don't like it. You can verify the source code and build it on your own using the instructions above, or set an exception case in the antivirus program for ThMouseX (including the DLLs).

ThMouseX doesn't work with old versions of Fantastic Danmaku Festival I (or games that use .NET Framework 2/3)

Old (pre-Steam) versions of Fantastic Danmaku Festival use .NET Framework 2, so normally this tool will not work because it uses .NET Framework 4. But you can force the game to use .NET Framework 4 by putting this text file to the same place with THMHJ.exe:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <startup useLegacyV2RuntimeActivationPolicy="true"> 
        <supportedRuntime version="v4.0"/>
    </startup>
</configuration>

Ensure the name of this manifest file is THMHJ.exe.config, not THMHJ.txt or THMHJ.exe.config.txt.

This can also be applied to other applications that use .NET Framework 2/3.