Skip to content

Support client-side image uploading - #87

Open
yqs112358 wants to merge 1 commit into
Patbox:mainfrom
YQ-Fabric-Mods:feat/client-upload-image
Open

yqs112358 wants to merge 1 commit into
Patbox:mainfrom
YQ-Fabric-Mods:feat/client-upload-image

Conversation

@yqs112358

@yqs112358 yqs112358 commented Sep 30, 2026 •

Copy link
Copy Markdown

Implements #72, allowing players to upload images directly from their computer without uploading to an image hosting service. This offers players a great deal of convenience.

Clients running the new version can upload a local image directly with /image2map create dither C:/Some-Dir/image.png, or use /image2map create dither to open a file picker and select a local image.

While the older version of the client mod (or not install the client mod) is still compatible. The image2map commands remain server-side.

Local upload flow

Players use /image2map create or /image2map preview with a local path, or omit the path to open a file picker. The client displays the supplied path for confirmation, or opens a file picker and asks the player to confirm their selection.

Upload with local-path
image

... or leave the path blank to use a file picker to choose a local image
image

After confirmation, the client reads and validates the image, then sends its metadata (e.g. format, size and dimensions) to the server. Once the server accepts this information, the client transfers the image in small chunks (16 KB) to the server. The server checks the received content and continues with map creation or preview.

Safety & lifecycle

To protect the server from attacks, upload messages must match a player's active create request. The actual image format and dimensions are verified before decoding, with the same checks applied to downloaded and server-local images.

These checks are coordinated by a per-player state machine: IDLE → CLIENT_SELECTING_IMAGE → GETTING_IMAGE → PROCESSING_IMAGE → PREVIEWING (optional) → IDLE. Each player can have one image operation or preview open at a time. All the situations like completion, cancellation, failure, transfer timeout, disconnect and preview closure are well-handled for this state machine.

Meanwhile, to protect clients from malicious servers, file contents are read by client mod only after explicit player confirmation.

Configurations

This PR updates the configuration to version 2, adds some new options and renames some existing options to clarify their purpose. To be specific,

  • maxSize becomes imageMaxWidthHeight, retaining its role as the output dimension limit.
  • allowLocalFiles becomes allowServerLocalFiles.
  • Add new settings cover upload access, file size, allowed formats, operation cooldown and network timeout. Defaults include a 20 MiB file limit, a five-second cooldown (to prevent client-DDoS) and a 30-second network timeout.

An example of the new configuration is shown below:

{
  "version": 2,
  "allowServerLocalFiles": false,
  "allowClientUploadFiles": true,
  "minPermLevel": 4,
  "imageMaxWidthHeight": 2048,
  "imageFileMaxSize": 20480,
  "allowedImageFormats": [
    "png",
    "jpeg",
    "gif",
    "bmp",
    "webp"
  ],
  "imageOperationCooldownSeconds": 5,
  "networkTimeout": 30
}

Existing configurations without a version field are migrated automatically, preserving the renamed values and filling new settings with defaults.

@yqs112358

Copy link
Copy Markdown
Author

I have tested this new version on my own Minecraft server for some hours, and it works well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant