OpenToonz新手入门：4步从源码跑通第一个2D动画项目-育师

OpenToonz新手入门：4步从源码跑通第一个2D动画项目

【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz

OpenToonz 是由 DWANGO 发布的开源2D动画软件，脱胎于 Toonz Studio 吉卜力版本，面向独立动画师和小型工作室，覆盖逐帧绘制、摄影台、合成特效到导出的完整流程。本文以 Linux 为例从源码把它跑起来，讲清常用配置文件，最后走一遍完整的动画制作工作流。

一、先看清 OpenToonz 的定位与边界

一套完整的2D工作流：逐帧绘制、Xsheet 时间轴、Camera 摄影台、合成 fx、导出都在一个程序里，不需要拼凑多套工具；但它是纯2D软件，不做3D。
有吉卜力级生产血统：仓库自带一套生产级素材，stuff/library/ 下的笔刷、纹理、粒子、着色器拿来就能用。
开放二次开发：核心是 C++/Qt 代码，位于 toonz/sources/；plugins/ 目录里已有 blur、geom 等示例插件，照这个模式可以扩展自己的功能。

二、把它跑起来：4步到首次启动

1. 获取代码（⭐，约5分钟）

git clone https://gitcode.com/GitHub_Trending/op/opentoonz

仓库内含 vendored 依赖目录 thirdparty/（tiff、SuperLU、OpenBLAS 等），克隆体积偏大，网络保持在线即可。

2. 安装构建依赖（⭐⭐，约10分钟）

Linux 用户按 doc/how_to_build_linux.md 操作，Debian/Ubuntu 一条命令装齐：

sudo apt-get install build-essential git cmake pkg-config libboost-all-dev qtbase5-dev libqt5svg5-dev qtscript5-dev qttools5-dev qttools5-dev-tools libqt5opengl5-dev qtmultimedia5-dev libqt5multimedia5-plugins libqt5serialport5-dev libsuperlu-dev liblz4-dev libusb-1.0-0-dev liblzo2-dev libpng-dev libjpeg-dev libglew-dev freeglut3-dev libfreetype6-dev libjson-c-dev qtwayland5 libmypaint-dev libopencv-dev libturbojpeg-dev

Windows 与 macOS 分别查 doc/how_to_build_win.md 和 doc/how_to_build_macosx.md，依赖清单相同，包管理器不同。

3. 构建（⭐⭐⭐，30~60分钟）

项目依赖经过修改的 libtiff，需要先编译 thirdparty/tiff-4.0.3：

cd opentoonz/thirdparty/tiff-4.0.3 ./configure --with-pic --disable-jbig && make -j$(nproc)

再回到主工程构建：

cd opentoonz/toonz mkdir build && cd build cmake ../sources && make -j$(nproc)

CMake 偶尔漏识别依赖，比如 SuperLU 找不到时，给 cmake 显式加参数-DSUPERLU_INCLUDE_DIR=/usr/include/SuperLU。

4. 首次启动（⭐）

OpenToonz 运行时从~/.config/OpenToonz/读配置和素材，先把仓库的 stuff 目录复制过去（这一步官方文档标注为必需）：

mkdir -p $HOME/.config/OpenToonz cp -r opentoonz/stuff $HOME/.config/OpenToonz/

然后在构建目录启动：

LD_LIBRARY_PATH=./lib/opentoonz:$LD_LIBRARY_PATH ./bin/OpenToonz

三、常用目录与3个实用配置点

目录/文件	用途
toonz/sources/	核心 C++/Qt 源码，读实现和二次开发都从这里入手
stuff/config/	运行时配置：qss/ 界面主题、reslist.txt 分辨率预设、permissions.xml 权限
stuff/library/	素材库：矢量笔刷、MyPaint 笔刷、纹理、粒子、场记板模板
stuff/profiles/layouts/	工作区布局与快捷键预设，分 rooms/、toolbars/、shortcuts/ 子目录
thirdparty/	随仓库分发的依赖库，构建环境配置时才会用到

切换界面主题

改哪里：LESS 源码在 stuff/config/qss/Default/less/，编译后的主题分散在 Default、Blue、Dark、Clay、Neutral、Light、Darker、Default-Green 八个 qss 子目录里。
怎么改：修改对应主题的 .less 文件，用 lessc 编译输出 .qss，例如lessc -x …/blue-theme.less stuff/config/qss/Blue/Blue.qss，共8套主题可选。
注意什么：.qss 是编译产物，直接改它下次编译会被覆盖；完整流程见 doc/how_to_stylesheet.md，改完记得同步到用户配置目录下的同名位置。

管理快捷键预设

改哪里：stuff/profiles/layouts/shortcuts/ 下的 ini 文件。
怎么改：defopentoonz.ini是默认映射，otadobe.ini、otharmony.ini、otanimate.ini、otretas.ini分别为从 Adobe、Harmony、Animate、RETAS 转过来的用户准备的预设，在软件设置里选一个即可。
注意什么：ini 文件定义按键映射，想自定义前先备份原文件，避免误改无法还原。

自定义摄影台分辨率预设

改哪里：stuff/config/reslist.txt。
怎么改：每行一个预设，格式为“名称, 宽x高, 宽高比”，例如已有的HD 1080, 1920x1080, 16/9，照格式追加一行就是自己的预设。
注意什么：这个文件是摄影台分辨率清单，不是素材路径；格式写错预设不会出现在下拉列表里，排查时先看分隔符。

四、实战：用场记板素材走通一次逐帧动画

以 stuff/library/clapperboards/ 的分镜场记板素材为起点，走一遍典型流程。

建项目：首次启动后在 Camera 房间新建项目，分辨率直接选 reslist.txt 里现成的 HD 1080（1920x1080）。
引入场记板模板：目录里有preset_sample.clapperboard预设和 16:9 模板图，把预设导入项目作为起始镜头。

逐帧绘制：切到绘制房间，从 stuff/library/vector brushes/ 选一支笔（41 支 .pli 矢量笔刷），在 Xsheet 里排帧并绘制关键帧。
加特效（可选）：粒子特效在 fx 里加载 stuff/fxs/presets/STD_particlesFx/ 的预设参数，粒子贴图素材放在 stuff/library/particles/。
导出：到 Export 房间渲染，输出视频或图片序列。

五、新手容易踩的3个坑

现象：构建成功，但启动./bin/OpenToonz直接报错，或界面缺资源。原因：OpenToonz 运行时只认~/.config/OpenToonz/下的配置和素材，stuff 目录还没复制过去。解法：执行cp -r opentoonz/stuff $HOME/.config/OpenToonz/再启动，Linux 上这一步是必需的，别跳。

现象：cmake 阶段报 SuperLU 未找到。原因：系统没装 SuperLU，或装了但头文件路径没被 CMake 识别。解法：Debian/Ubuntu 装libsuperlu-dev，或给 cmake 显式传-DSUPERLU_INCLUDE_DIR=/usr/include/SuperLU；Fedora 一般能自动识别。

现象：改了 .qss 颜色不生效，或者下次编译又被覆盖回去。原因：主题由 LESS 源码编译生成，.qss 只是构建产物，不是源头。解法：到stuff/config/qss/Default/less/改 .less 文件，用lessc -x编译到对应主题目录，再同步到用户配置目录。