Best Practices for Files on Roll20

Web-Friendly vs. Print Images

If you are playing from a commercial adventure pack, there is a high chance you are working from a PDF file. In order for graphics to be readable and crisp for print, the image resolution, or DPI (Dots per inch) has to be kept rather high, at least 300 DPI for most print-quality PDFs. Higher DPI (dots per inch) results in larger image file sizes and puts more strain on the processor to display the image. This means maps, character portraits, and handouts from commercial PDFs are going to be larger file sizes than necessary for a Roll20 Game. TL/DR: If you just drag these assets into your game, it will eat up your storage space.

If you want images to run smoothly in Roll20, we recommend keeping image resolution low. Anywhere between the 70-150 DPI range should be adequate for your game images. This can be accomplished by adjusting the resolution using image-editing software. We also offer optimized assets through our Roll20 Marketplace.

File Types

Image Files

The three available image file types that can be imported and used in Roll20 are JPG, GIF, and PNG. As of late February 2024, the maximum upload size is 20MB for Free users and 50MB for Plus users and 100MB for Pro users. 

Let’s compare the file formats against each other:

JPEG is Roll20’s preferred image file type. JPEG files offer smooth gradients and a small file size. However, there are no transparency options, and quality can suffer when a JPEG is heavily-compressed. If you have graphics that don’t require any transparency or translucency, stick with JPG image files.
File size: Average
Can it be transparent? No
Can it be translucent? No
Can it animate? No

GIF files are suitable for pixel art, offer palette swatch control, and animated GIFs can be displayed on the Roll20 virtual tabletop. However, GIF files are bad at replicating gradients, are limited to a 256 “indexed” color palette, and are not suited for producing realistic images. The GIF file type is handy if you want just a simple aliased cutout image for token objects, with or without animation.
File size: Small
Can it be transparent? Yes
Can it be translucent? No
Can it animate? Yes

PNG files offer lossless compression, which yields high-quality images. However, the file size increases dramatically when using extensive alpha channel work, and the larger PNG files use up a lot of system resources. PNG is an ideal format for solid drawings and images with large swaths of exactly the same color. PNGs can also work for token objects or images requiring transparency, but animated PNG files are not supported. PNGs are more flexible than GIFs, which can lead to larger file sizes even for visually similar images.
File size: Large
Can it be transparent? Yes
Can it be translucent? Yes
Can it animate? No  

Tip: If your software allows you to do so, you may be able to change your image from "full color" or "RGB" to "palette" or "indexed". The latter option has a limited number (usually 256) of colors and is the only format that GIF supports. This is why GIF files are smaller. PNG files using the same type of palette will be roughly the same size as GIF images. Compared to GIF, most PNG files are in RGB format, storing more data per pixel and resulting in larger file sizes. However, this preserves image integrity to a greater extent.

 

Animation Files

For animated files on Roll20, we support three file types: GIF, mp4, and webm. As of late February 2024, the maximum upload size is 20MB for Free users and 50MB for Plus users and 100MB for Pro users. 

Let’s compare the animated file formats against each other:

GIF files, as stated in the above image section, offer palette swatch control upon creation, they’re great for pixel art, and animated GIFs will animate on the Roll20 virtual tabletop. However, GIF files are bad at replicating gradients, are limited to a 256-color palette, and are not suited for producing realistic images. Because they store more data per animation frame than other formats, large animations perform poorly.
File size: Small
Can it be transparent? Yes
Can it be translucent? No

MP4 files are actually video file formats, which translate to a better experience. Transparency (called an Alpha channel) is not supported by this file type. Animated maps and backgrounds work well in this file type. Once uploaded to Roll20, these files will not retain audio from the original file. MP4 format lacks transparency options and may experience reduced quality with heavy compression. For animations, MP4 files will be more available, but converting MP4 to WEBM will reduce the time it takes to put your files on Roll20.
File size: Large, better efficiency
Can it be transparent? No
Can it be translucent? No

WEBM is engineered for use on the web. Supports transparency and translucency (with 8-bit Alpha Channel). WEBM files offer as much quality as MP4 but in a much smaller size. The main drawback is that this file type is not as universal as MP4 or GIF.
File size: Small, most efficient
Can it be transparent? Yes
Can it be translucent? Yes  

As of March 2025, Roll20 released an update to the graphic upload process that should result in faster and more efficient uploads.

Previously, your browser was relied upon to handle transcoding using JavaScript (an inefficient and CPU-heavy process), which slowed down the process and your machine considerably. Now, we’ve moved this work to dedicated servers that process more quickly without burdening your machine. The benefits of this update include:

• Drastically faster uploads: large files that previously took hours to finish now complete in minutes. Our tests indicated an average decrease in upload time of 76% across a variety of animated files, with some performing up to 98% faster, and many files that did not finish previously now succeeding in an average of four minutes
• Higher animation quality: reduced pixelation and smoother playback
• Reduced slowdown: particularly noticeable on machines that lacked the power to transcode previously, moving this process to our servers frees your machine for other tasks

FAQs

• Q: Will this update affect existing animations previously uploaded to my campaigns?
  No. To take advantage of upgrades, assets will need to be re-uploaded.
• Q: Do the animation upload upgrades affect all file sizes?
  Yes, but the performance improvements will be most noticeable with larger animation files.
• Q: Will this impact animated assets purchased from the Roll20 Marketplace or gifted through Roll20 Reserve?
  No. These upgrades apply to animated assets that you upload directly to your campaigns.
• Q: Could there be cases where animation quality or performance is worse than before?
  That is not our expectation or experience in testing. If you do experience any issues, please let us know. We plan to fine-tune settings over time for even better performance. For example: we’re gathering insights on common file types, animation sizes, and use cases (like graphics vs. maps) to help optimize quality similar to how we manage Lighting Texture today.
• Q: Could some animations upload slower compared to the old process?
  For very small GIFs, you might notice a slight delay of a few seconds due to the new server-side processing queue. Additionally, the new upload process is aiming to achieve higher animation fidelity and resolution to increase animation quality, which may have slight impacts to the upload timing. However, in the majority of cases and especially for larger files, the new process should be significantly faster overall.
• Q: Are there any other factors that could affect how animations load in-game?
  While the upload process is now faster and more efficient, internet speed and bandwidth can still impact individual experiences. Larger animations may take extra time to fully load for players depending on their hardware and connection. In our internal tests, files close to 100MB could take 10-20 minutes to fully load on 3G connections, leading to potential choppines or static images to display during that time.
• Q: What factors impact upload time, and what’s a reasonable expectation?
  File size and resolution, animation length and complexity, and computer bandwidth and internet speed can all impact uploads. For very large animations (~90MB, high resolution, complex effects), uploads could take 20+ minutes in rare cases. However, most uploads should finish within 10 seconds to 5 minutes.
• Q: What is transcoding, and how does it affect my storage?
  Storage usage for animated graphics is based on the final transcoded file size, not the original upload.

  Transcoding is the process of converting video files into standardized formats optimized for display on the virtual tabletop. We use industry standard ffmpeg to ensure that your animations retain their quality while improving playback performance, maintain visual consistency (like keeping transparency settings intact), and minimizing load time variability. Because different codecs handle compression differently, transcoding may sometimes reduce file size, but if your original file is already highly compressed, it could increase in size.

• Q: Why is my storage usage different from file upload size for animated files?
  With the updated animation upload process, storage usage is based on the final transcoded file size - the actual size of storage on Roll20 servers - rather than the original upload size.

  We transcode files to a specific bitrate to maintain animation quality and consistency on the Tabletop. This helps prevent heavy artifacting and blocking in large, high-resolution animations (like maps) while ensuring smaller animations (like tokens) remain compact and bandwidth-efficient. Additionally, this process prevents extremely high bitrate uploads from being shared with your players, which could otherwise reduce VTT performance without meaningful benefit.

  Note: We use Mebibytes (MiB) to reflect storage, not Megabytes (MBs). Be sure to check the units when comparing file sizes on your computer.

• Q: Where can I find the final storage usage?
  Once your file has finished uploading, you can check its final storage usage in two places:
  a) Upload Art Modal accessed via Art Library > Upload
  b) Uploaded Assets Modal accessed via Art Library > Uploaded Assets section (double-click on the item)

  Note: storage is displayed in Mebibytes (MiB), not Megabytes (MBs). Be sure to check the units when comparing file sizes on your computer.

• Q: Can I adjust my files to reduce storage usage?
  Yes, you can reduce the resolution of your animations before uploading them using tools like: ffmpeg, HandBrake, or video editing software like Adobe Premiere Pro. However, since storage is based on the transcoded file size, not the original (see questions above), keep in mind that extreme compression may not significantly impact space saved after processing.

Working with Screen Space

When a GM hands out documents to their players around a physical table, the item is usually written or printed on portrait-oriented paper. On a tablet, a person can simply flip the screen whether a graphic is either Portrait or Landscape. Flipping a screen can’t really be done on a computer monitor. When you want to create handouts or splash screens for use in Roll20, keep in mind that the average user often is working on a widescreen monitor with fixed screen resolution. You want to create and plan out handouts and splash screens that’ll fit nicely on the collective user’s screen. Instead of thinking portrait/vertical, go with landscape/horizontal orientation for notes, letters, pictures, or anything else that isn’t going to be a tabletop map.

Regarding screen resolution, get an idea of what your players are using. Are they working at desktop stations? Tablets? Laptops? Find a happy medium of screen resolution and adjust your graphic sizing accordingly to avoid forcing others to adjust their zoom settings in order to view your images. Websites like w3schools.com keep yearly tallies of the average screen resolution over the years if you need a generic design guide.

Roll20 Image Dimensions

Here are specific Roll20 dimensions for certain graphic elements.

Image Dimensions

* The hex grid is mathematically drawn, so the pixel height and width for a single hex unit is an approximation

Token Images

Due to their small size, token images are best suited for PNG formats for best quality. PNGs also offer transparency. If you are not using a square or hex grid for token movement, you don't need to worry about the actual dimensions of the image. If you are using a grid, however, you will want to make sure your image has enough transparent padding. The reason for doing this is that when an image is dropped onto a gridded tabletop, Roll20 will warp the dimensions of the image to best sit inside a single grid unit. This process might change the proportions of your image. For instance, if you are using tokens that fill a 1 x 1, 2 x 2, or 3 x 3 unit space, you will want to make sure that the final dimensions of the image are the same for both height and width. If you have an oblong token, you will want to make sure that the final dimension of either the width or height is exactly double or perhaps triple the other.

Common Problems: