TCPGecko Plugin

日本語

TCPGecko Plugin is a Wii U Aroma plugin that exposes a TCP Gecko-compatible server for development, debugging, memory inspection, and cheat-code workflows. The server listens on TCP port 7331.

Warning

TCPGecko provides powerful memory and code-execution commands. Use it only on a trusted local network and only with software and hardware you are authorized to inspect.

Features

• TCP Gecko-compatible server on port 7331
• User and kernel memory read/write commands
• General and latest code-handler modes
• SD .gctu cheat loading and optional combination with client-uploaded codes
• Breakpoint, thread, stack-trace, symbol, memory-search, and remote-call commands
• Screenshot and file-operation support
• Persistent raw assembly execution
• Configurable server enablement and thread priority through the WUPS configuration menu

Some low-level commands can crash the running title or the console when given invalid addresses or code. Save your work before testing.

Requirements

Wii U

• A Wii U running Aroma
• WiiUPluginLoaderBackend
• NotificationModule
• A TCP Gecko-compatible client on the same trusted network

Use mutually compatible versions of Aroma and its modules. The current Aroma package normally supplies the required runtime modules.

Building

The recommended build path requires Docker Desktop or another Linux-container-compatible Docker installation. A native build requires devkitPro/devkitPPC, WUT, WiiUPluginSystem, libwupsbackend, libnotifications, and the port libraries referenced by the Makefile.

Installation

1. Build the project or obtain TCPGeckoPlugin.wps from a trusted release.

2. Copy it to:

   sd:/wiiu/environments/aroma/plugins/TCPGeckoPlugin.wps
   

3. Start Aroma or reload its plugins.

4. Open the Aroma/WUPS plugin configuration menu to change TCPGecko settings.

5. Connect a compatible client to the Wii U's local IP address on port 7331.

For a non-default Aroma environment, replace aroma in the path with that environment's directory name.

Configuration

Setting	Purpose
Enable TCPGecko	Starts or stops the TCPGecko service. Disconnect the client before changing it.
Code Handler	Selects the general or latest embedded code handler.
Enable SD cheats	Loads the current title's .gctu file from the SD card.
Combine SD and client cheat codes	Appends SD codes when compatible codes are uploaded by a client.
Serialize assembly execution	Enables the existing mutual-exclusion behavior around persistent assembly execution.
TCPGecko thread priority	Selects low, normal, high, or real-time priority. Use real-time with care.

SD cheat files use this layout:

sd:/codes/<16-digit-title-id>.gctu

For example, use the title ID as 16 uppercase hexadecimal digits followed by the .gctu extension.

Docker build

From the repository root:

docker build --tag tcpgecko-plugin-builder .
docker run --rm --volume "${PWD}:/project" tcpgecko-plugin-builder make -j2

The build creates these files in the repository root:

• TCPGeckoPlugin.wps — installable Aroma plugin
• TCPGeckoPlugin.elf — ELF build artifact for development and symbol inspection

To build with logging:

docker run --rm --volume "${PWD}:/project" tcpgecko-plugin-builder make DEBUG=1 -j2

For verbose logging:

docker run --rm --volume "${PWD}:/project" tcpgecko-plugin-builder make DEBUG=VERBOSE -j2

Clean generated files separately before switching build modes:

docker run --rm --volume "${PWD}:/project" tcpgecko-plugin-builder make clean

These commands work in PowerShell and POSIX-style shells. On Windows, Docker Desktop must be using Linux containers.

Native build

After installing the dependencies and setting DEVKITPRO, run:

make -j2

The Makefile supports the same DEBUG=1 and DEBUG=VERBOSE options as the Docker build.

Project layout

src/main.cpp                 Plugin metadata, lifecycle, settings, and storage
src/tcpgecko/                TCP Gecko protocol and code-handler implementation
src/tcpgecko/libs/           Wii U filesystem, patching, sound, and system helpers
src/utils/                   Logging, exceptions, threading, and general utilities
Dockerfile                   Reproducible devkitPPC/WUPS build environment
Makefile                     Source list, compiler options, and link dependencies

Contributing

Keep changes focused and readable, and preserve existing copyright notices. Before submitting a change:

1. Run a clean normal build.
2. Run a clean DEBUG=1 build when changing logging or diagnostics.
3. Run git diff --check.
4. Describe any runtime validation performed on a Wii U or emulator separately from build-only validation.

Credits

This project is a fork of BullyWiiPlaza/tcpgecko, adapted for use as an Aroma plugin by Katope. This project also contains work from TCP Gecko and Wii U homebrew contributors; individual source files retain their applicable copyright and license notices.

License

This project is distributed under the GNU General Public License v3.0, matching the upstream project. Files containing additional notices remain subject to those notices. See LICENSE for the full terms.

This project is not affiliated with or endorsed by Nintendo.