Creating documentation images and videos

Creating documentation images and videos

Throughout the documentation, images are often needed to make the explanation of a feature or concept as clear as possible for a reader. This page will explain the process from beginning to end.

图像

截图

To take a picture of something in Godot, a screen capture tool can be used.

在 Windows 10 和 11 上，这将是 Snip & Sketch 程序。按 Windows + Shift + S 可以截取屏幕一部分的屏幕截图并将其保存到剪贴板。按下这些键后，点击并拖动你想要截取的区域。

在 macOS 上，按 Shift + Command + 3 有相同的效果。要拍摄整个屏幕的照片，请按 Shift + Command + 4。所有截取的屏幕截图都将保存到桌面。

每种Linux桌面环境都有自己的屏幕截图工具。比如，在KDE Plasma（译者注：一种linux桌面环境）中，Spectacle 程序用于拍摄截图。如果你的发行版默认没有截图工具，尝试搜索包存储库。如果支持也可以搜索Flathub（译者注：一种Linux应用商店）。

所有的屏幕截图最好在1080p分辨率屏幕上截取。使用更高分辨率会增加无谓细节，这不但不能使文件更好，而且会显著增加文件大小。如果你在更高分辨率的屏幕上截图，截图应该缩小。在本页的后面，会有关于如何执行此操作的说明。

格式转换

The current format for images in Godot’s documentation is WebP (.webp). While some Linux programs will support saving screenshots in this format, macOS and the Snip & Sketch program on Windows do not. For images that don’t need editing, such as precise cropping or adding outlines, Squoosh can be used. Squoosh is a converter developed by Google, is open source, and doesn’t give Google any image rights by using it. When choosing compression if you can get an image that’s under 300KB in size use lossless compression. If it’s over 300KB, use just enough lossy compression to get it under that size. If this results in noticeable compression artifacts using less compression is fine, even if the file size is bigger.

如果你已经安装了图像编辑器，比如GIMP，Krita或者Photoshop，这些软件可以打开图像，然后将其保存为一个WebP（译者注：一种图像文件格式）文件。

裁剪

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 to make an image look clean. Below is an example of good cropping.

对于图片裁剪这里推荐 Krita。虽然某些屏幕截图程序确实内置了裁剪功能，但获得精确的结果并不那么容易。虽然 Krita 被设计为绘画程序，但其裁剪工具默认提供像素精度。当然，你也可以随意使用你熟悉的其他程序。

If you’ve never used Krita before download it from the official 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 then open the image you want to crop. This button on the left panel is the crop tool.

选择它后，单击图像，现在应该可以使用裁剪工具。

点击并拖动白色框以调整裁剪的内容，如果放大图像，你将看到图像中的各个像素，这对精度很有用。

如果你编辑失误并且进行了过度裁剪，请不要担心，Krita 中的裁剪是非破坏性的，并且可以进行调整。在仍选择裁剪工具的情况下单击图像，控件将返回。

缩小图像

正如本页前面所解释的，在分辨率高于 1080p 的屏幕上拍摄的所有图像都应按比例缩小。要在 Krita 中执行此操作，请单击顶部栏上的图像，然后从下拉菜单中选择 将图像缩放到新尺寸 。也可以通过按 Ctrl + Alt + I 打开此菜单。在此菜单上调整像素尺寸。对于在 4K 显示器上拍摄的任何内容，请将宽度和高度的值更改为其当前值的一半；对于在 1440p 显示器上拍摄的任何内容，请将宽度和高度乘以 0.75。确保选中菜单底部的 约束比例 框，这样只需更改 1 个值。

在 Krita 中保存为 WebP

To save an image as webp if it isn’t already one, Go to File > Save As. Select webp from the Save as type: dropdown, then choose wherever you want to save it. After clicking Save a menu will popup with webp options. Make sure Lossless is checked and Quality is set to 100%. This means 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 using Squoosh. If it’s still over 300KB change to lossy compression and slowly increase the compression until it’s under 300KB. If this results in noticeable compression artifacts using less compression is fine, even if the file size is bigger.

Outlines, arrows and text

有时，一张图片需要一些额外的东西来适当的引导读者的注意力，或者让一些东西变得清晰。轮廓线和箭头可以用于此目的。对于这些类型的编辑，Inkscape 是推荐的开源程序，可以从`Inkscap 官方网站<https://inkscape.org/>`_ 下载。像 Krita 一样，如果你在 Linux 上，你也可以检查你的发行版仓库或从 Flatchub 获取。

这里没有提供关于创建轮廓的完整教程，我们建议搜索各种关于如何在线使用它的教程。但是，文档图像轮廓和箭头有两个标准。首先，颜色应该是黄色，特别是这种十六进制颜色： fffb44 （如果有像 Inkscape 中那样的透明度值，则为 fffb44ff ）。选择这种颜色是为了确保色盲在阅读文档时不会遇到问题，如果需要在图像上使用多个轮廓，则除了这种黄色之外，还可以使用其他颜色，应避免使用红色。第二个标准是所有的轮廓和箭头线都应该是 2 像素宽。

最后，一些图像可能需要文本来区分图像的多个部分。除了使用易读的非花哨字体外，没有其他严格的要求。至于颜色，也应该使用以前的黄色，但如果合适，可以使用黑色或其他颜色。例如，如果黄色混合到图像中，或者如果存在多种颜色的多个轮廓。

将图像添加到文档页面

完成图像处理后，就可以将它添加到文档中了。所有的图像都保存在使用它们的页面旁边的名为 img 的文件夹中。

要添加图像，请将其添加到 img 文件夹中，该文件夹与页面的 .rst 文件位于同一文件夹中（如果不存在，请创建它）。在 .rst 页面中，图像应包含在以下代码段中

.. image:: img/documentation_image.webp

其中 documentation_image.webp 将更改为所创建图像的名称。以明确的方式为图像命名，可以的话使用前缀明确表示它们与文档页面的关系。

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 enough for this, so you’ll need to install a third-party utility.

OBS Studio is the most popular option, but SimpleScreenRecorder can be used as an alternative on Linux. ShareX can be used as an alternative on Windows. All these tools can be configured to record the entire screen, a specific window or a predetermined rectangle.

The recommended framerate for video recordings is 60 FPS, although you can use 30 FPS for longer videos to reduce their file size. For fullscreen videos, use a resolution of 1280×720.

备注

Godot’s Movie Maker mode can be used to record the output of a running project, including its audio. This doesn’t require installing any third-party software and avoids any frame drops (even when recording 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-encode it later to reduce its file size. This results in more efficient compression than directly aiming for a small file size, as real-time compression methods are less efficient than slower compression methods.

To re-encode videos for a smaller file size, use HandBrake or the FFmpeg <https://ffmpeg.org/> command line below:

ffmpeg -i input.mp4 -crf 23 output.webm

The number after -crf adjusts the video quality, with higher numbers resulting in lower quality (and smaller file sizes). A CRF of 23 is a good starting point, but you may need to use a higher value for longer videos to ensure the file size remains reasonable. Try to aim for a file size under 2 MB if possible.

If the video was recorded in a higher resolution or framerate, you can adjust its output resolution and framerate as follows:

ffmpeg -i input.mp4 -crf 23 -vf scale=1280:-2 -r 30 output.webm

This results in a video resolution around 1280×720 at 30 FPS. The exact video resolution will vary depending on the source’s aspect ratio.

小技巧

If the video was recorded with an audio track but this audio track is not necessary, consider stripping it by adding the -an option to the FFmpeg command line (before the output file name). This will reduce file size and also ensure audio controls don’t show up on the video when played in a browser.

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 named video next to the page they are used in.

To add your video, add it to the video 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: Put a text description of the video here
   :autoplay:
   :loop:
   :muted:

Where documentation_video.webp would be changed to the name of the video you created. Name your videos in a way that makes their meaning clear, possibly with a prefix that makes their relationship to a documentation page explicit.

The :autoplay:, :loop: and :muted: flags should always be specified unless the video needs to play audio. In this case, do not specify any of these flags.