Attention: Here be dragons
This is thelatest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Creating documentation images and videos
Throughout the documentation, images are often needed to make the explanationof a feature or concept as clear as possible for a reader. This page willexplain the process from beginning to end.
Images
Capturing an image
To take a picture of something in Godot, a screen capture tool can be used.
On Windows 10 and 11 that would be the Snip & Sketch program.PressingWindows+Shift+S lets you take a screenshotof a portion of the screen and save it to the clipboard.After pressing those keys, click and drag overthe area you wish to take a picture of.
On macOS, pressingShift+Command+3 does the same.To take a picture of the entire screen pressShift+Command+4.All screenshots taken will be saved to the desktop.
Each Linux desktop environment has its own screenshot tool. For example,on KDE Plasma the program Spectacle is used for taking screenshots. If yourdistribution doesn't come with one by default try searching its packagerepository, or Flathub if that's supported.
All screenshots should ideally be taken on a 1080p screen. Anything higherresolution is adding detail that doesn't make the documentation better anddramatically increases file size. If you're taking screenshots on a higherresolution screen the screenshot should be scaled down. There are instructionson how to do this later on this page.
Format conversion
The current format for images in Godot's documentation is WebP (.webp).While some Linux programs will support saving screenshots in this format, macOSand the Snip & Sketch program on Windows do not. For images that don't needediting, such as precise cropping or adding outlines, Squoosh can be used.Squoosh is a converter developed by Google, is opensource, and doesn't give Google any image rights by using it. When choosingcompression if you can get an image that's under 300KB in size use losslesscompression. If it's over 300KB, use just enough lossy compression to get itunder that size. If this results in noticeable compression artifacts using lesscompression is fine, even if the file size is bigger.
If you already have an image editor such as GIMP, Krita or Photoshop installedit may have the ability to open an image then save it as a WebP file.
Note
Since WebP supports animations and the documentation can display videos,GIFs should be avoided. Their compression is inefficient and they only supporta 256-color palette with 1-bit transparency.
Cropping
For a screenshot of a 2D or 3D scene in the editor, the above steps will be enough.But for most UI images some extra work should be done, specifically cropping tomake an image look clean. Below is an example of good cropping.
For cropping Krita is the recommended program. While some screenshot programs dohave cropping built-in it's not always easy to get something precise. And whileKrita is designed as a painting program the cropping tool gives you pixel precisionby default. Of course, feel free to use a different program you are familiar with.
If you've never used Krita before download it from theofficial Krita website,on Linux you may also be able to download it from your distributions repository,flathub is also an option. Once it's installed on your computer open Krita thenopen the image you want to crop. This button on the left panel is the crop tool.
After selecting it, click on the image, you should now have cropping tools available.
Click and drag the white boxes to adjust what gets cropped, if you zoom in closeto the image you will see the individual pixels in an image, which is useful forprecision.
If you make a mistake and overcrop don't worry, cropping is non-destructive inKrita and can be adjusted. Click on the image with your cropping tool still selectedand the controls will return.
Scaling down an image
As explained earlier on this page, all images taken on a screen that is a higher resolutionthan 1080p should be scaled down. To do this in Krita click onImage on the top bar, andfrom the dropdown menu selectScale Image To New Size. This menu can also be opened bypressingCtrl+Alt+I. On this menu you want to adjust the pixel dimensions. Foranything taken on a 4K monitor change the value of the width and height to half of its currentvalue, for anything taken on a 1440p monitor multiply the width and height by 0.75. Makesure theConstrain Proportions box at the bottom of the menu is checked so you only haveto change 1 value.
Saving as WebP in Krita
To save an image as webp if it isn't already one, Go toFile > Save As. Selectwebp from theSave as type: dropdown, then choose wherever you want to save it. After clickingSave a menuwill popup with webp options. Make sureLossless is checked andQuality is set to 100%. Thismeans the image will not lose detail and will be as small as possible.
If the image is over 300KB in size try compressing it losslessly usingSquoosh.If it's still over 300KB change to lossy compression and slowly increase the compression until it's under300KB. If this results in noticeable compression artifacts using less compression is fine, even if the filesize is bigger.
Outlines, arrows and text
Sometimes an image needs something extra to properly direct the readersattention, or make something clear. Outlines and arrows can be usedfor this purpose. For these types of edits Inkscape is the recommended opensource program, it can be downloaded from theofficial Inkscape website.Like Krita, if you're on Linux you can also check your distributions repositoryor get it from Flathub.
A full tutorial on creating outlines is not provided here, we recommend searchingfor various tutorials on how to use it online. However there are two standardsfor doc image outlines and arrows. First, the color should be yellow, specificallythis hex color:fffb44 (fffb44ff if there is a transparency value like in Inkscape).This color was chosen specifically to make sure color blind people do not haveissues reading the documentation, other colors can be used in addition to this yellowif multiple outlines on an image are needed, red should be avoided. The second standardis that all outlines and arrow lines should be 2 pixels wide.
Finally, some images might require text to differentiate multiple parts of an image.There are no strict requirements other than use an easy to read non fancy font. As forcolor the yellow color from before should also be used, but black or other colors canbe used if appropriate. For example, if yellow blends into the image, or if there aremultiple outlines in multiple colors.
Adding an image to a documentation page
Once you've finished working on your image, it can be added to the documentation.All images are stored in folders namedimg next to the page they are used in.
To add your image, add it to theimg folder that's in the same folder as the.rst file for the page (create it if it doesn't exist). In the.rst page,images should be included with the following code snippet:
..image::img/documentation_image.webp
Wheredocumentation_image.webp would be changed to the name of the image youcreated. Name your images in a way that makes their meaning clear, possibly witha prefix that makes their relationship to a documentation page explicit.
Videos
Capturing a video
To record a video of something in Godot, a screen capture tool can be used.Operating systems generally don't come with tools that are flexible enoughfor this, so you'll need to install a third-party utility.
OBS Studio is the most popular option, butSimpleScreenRecordercan be used as an alternative on Linux.ShareXcan be used as an alternative on Windows. All these tools can be configuredto record the entire screen, a specific window or a predetermined rectangle.
The recommended framerate for video recordings is 60 FPS, although you can use30 FPS for longer videos to reduce their file size. For fullscreen videos,use a resolution of 1280×720.
Note
Godot'sMovie Maker mode can be used to recordthe output of a running project, including its audio. This doesn't requireinstalling any third-party software and avoids any frame drops (even whenrecording on a slow device), but it's less flexible.
Compressing the captured video
The recommendation is to record your video in the highest quality possible(without dropping frames due to excessive CPU/GPU utilization), then re-encodeit later to reduce its file size. This results in more efficient compressionthan directly aiming for a small file size, as real-time compression methods areless efficient than slower compression methods.
To re-encode videos for a smaller file size, useHandBrakeor theFFmpeg <https://ffmpeg.org/> command line below:
ffmpeg-iinput.mp4-crf23output.webm
The number after-crf adjusts the video quality, with higher numbersresulting inlower quality (and smaller file sizes). A CRF of23 is a goodstarting point, but you may need to use a higher value for longer videos toensure the file size remains reasonable. Try to aim for a file size under 2 MBif possible.
If the video was recorded in a higher resolution or framerate, you can adjustits output resolution and framerate as follows:
ffmpeg-iinput.mp4-crf23-vfscale=1280:-2-r30output.webm
This results in a video resolution around 1280×720 at 30 FPS. The exactvideo resolution will vary depending on the source's aspect ratio.
Tip
If the video was recorded with an audio track but this audio track is notnecessary, consider stripping it by adding the-an option to the FFmpegcommand line (before the output file name). This will reduce file size andalso ensure audio controls don't show up on the video when played in abrowser.
Adding a video to a documentation page
Once you've finished working on your video, it can be added to the documentation.All videos are stored in folders namedvideo next to the page they are used in.
To add your video, add it to thevideo folder that's in the same folder as the.rst file for the page (create it if it doesn't exist). In the.rst page,videos should be included with the following code snippet:
..video::video/csg_tools.webm:alt:Putatextdescriptionofthevideohere:autoplay::loop::muted::align:default
Wheredocumentation_video.webp would be changed to the name of the video youcreated. Name your videos in a way that makes their meaning clear, possibly witha prefix that makes their relationship to a documentation page explicit.
The:autoplay:,:loop: and:muted: flags should always be specifiedunless the video needs to play audio. In this case, do not specifyany of these flags.The:align:default flag should always be specified.