Stuck Pal Scanner

Description

Stuck Pal Scanner automatically finds and rescues base Pals that have become trapped underground, stuck near a Palbox or unable to reach food.

SPS does not blindly teleport every worker. It watches how each Pal is moving, how far below the base it is and what it is currently doing before deciding whether a rescue is needed.

When a rescue is approved, the Pal is moved to a safe position above and around its Palbox so it can return to normal base activity.

Automatic Ground/Geometry Rescue

On dedicated servers, SPS opens a short rescue scan when a base is visited for the first time during that server session.

This is designed to catch Pals that loaded beneath the floor, fell underneath the base or became trapped around the Palbox during server startup.

Bases with a player inside can also receive additional scans. By default, the same base must wait at least 15 minutes before another scan can begin.

SPS also checks Palworld's actual base boundaries. This means bases enlarged by base-radius mods should be recognised automatically without requiring you to manually increase a distance setting.

SPS can detect:

• Pals partially embedded in the floor.
• Pals moving around underneath a base.
• Pals that have fallen far below the base.
• Large and Alpha Pals whose visible body does not match their reported position.
• Pals trapped around the Palbox without making meaningful progress.

Movement-Aware Detection

SPS checks horizontal and vertical movement separately.

A Pal running underneath the floor can still be rescued, while a Pal walking normally around the base is left alone.

Pals that are sleeping, fighting, eating, resting or otherwise in a protected state are not teleported unnecessarily.

SPS also recognises Pals working at valid assigned locations. Being marked as “working” will not, however, hide a Pal that is genuinely trapped underground.

Hunger Recovery & Rescue

SPS watches Pals that begin trying to reach food.

If a hungry Pal cannot reach food and remains unable to move for the configured amount of time, SPS can relocate it near the Palbox.

If the Pal reaches food normally, hunger tracking stops immediately and the Pal is protected from an unnecessary rescue.

Hunger rescue works on both dedicated servers and singleplayer.

Rescue Messages

SPS can display rescue updates through Palworld's system feed.

Ground rescues use messages such as:

6 Pals appear to be stuck in this base. Rescue operation underway...

6 Pals moved. Rescue operation for this base is complete.

Hunger rescues use their own messages:

2 Pals appear to be hungry & cannot reach food. Rescue operation underway...

2 Pals moved. Rescue operation complete.

Messages are grouped together to prevent spam and are shown only to players inside the affected base.

They can be disabled in config.lua with:

show_rescue_notifications = false

Safe Recovery and Verification

Rescued Pals are spread around an elevated recovery ring instead of being placed directly on top of the Palbox.

After moving a Pal, SPS checks whether it reached a safe height and returned to ordinary movement or base activity.

If the first landing does not work, SPS can try another position. If the Pal recovers naturally, any unnecessary retry is cancelled.

Monitoring Stand settings and work assignments are preserved throughout the rescue process.

Singleplayer

SPS automatically detects singleplayer. You no longer need to change a dedicated-server setting in config.lua.

Palworld's own save-load deployment remains responsible for placing base Pals when a singleplayer world loads, allowing Pals to deploy as they should, all at once.

SPS does not run its dedicated-server ground scans in singleplayer because the game's normal deployment is the better option there.

Hunger tracking and hunger rescue remain active in singleplayer.

Panthalus

Panthalus is deliberately ignored by SPS.

Its size makes it unsuitable for the normal recovery ring, and it generally loads correctly without SPS assistance.

The single KingWhale entry in config.lua handles this exclusion.

Server-Friendly Design

SPS is designed to avoid unnecessary work on busy servers.

• Only bases with a player inside are considered for recurring scans.
• No more than two bases share a recurring scan window.
• A rest period separates recurring scan windows.
• First-time base visits take priority.
• Rescues are processed in small groups instead of all at once.
• SPS checks the existing rescue workload before opening another scan.
• Missed scan times are not saved up and triggered together.
• Unattended and unloaded bases are not repeatedly scanned.
• Detailed logging is disabled by default.

Requirements

• UE4SS Okaetsu Experimental.
• For dedicated servers, UE4SS and SPS only need to be installed on the server. Connecting players do not need to install the mod.

Installation Instructions

1. Install UE4SS Okaetsu Experimental into your Palworld installation or dedicated server.
2. Extract the downloaded SPS archive into:

   Pal\Binaries\Win64\ue4ss\Mods</pre>

3. Confirm that the final folder looks like:

   Pal\Binaries\Win64\ue4ss\Mods\StuckPalScanner\Scripts\main.lua

4. Start Palworld or restart the dedicated server.

SPS will automatically detect whether it is running on a dedicated server or in singleplayer.

Troubleshooting

If SPS does not behave as expected:

1. Confirm that UE4SS and SPS are installed in the correct folders.
2. Confirm that StuckPalScanner appears in the UE4SS log.
3. Look for one of these messages:

   SPS v1.3.0: dedicated server detected
   SPS v1.3.0: singleplayer/listen server detected

4. Set the following option in config.lua:

   verbose_logging = true

5. Restart the game or server.
6. Reproduce the problem and provide the relevant UE4SS log.

Return verbose_logging to false afterwards to keep normal logs quiet.

If rescue messages do not appear, confirm that:

show_rescue_notifications = true

Messages are only sent to players currently inside the affected base.

Compatibility

SPS should work alongside most mods because it only acts on Pals that meet its rescue conditions.

Base-radius expansion mods are supported automatically when Palworld reports the enlarged base boundary correctly.

Mods that completely replace base deployment, Pal AI, hunger behaviour or base-worker handling may interfere with SPS.