Live2D Cubism link

Live2D Cubism 是一種使用2D圖片製作動畫的系統，可以用在視覺小說的角色精靈中。這些2D圖片會繪製在幾個不同的圖層中——例如，瞳孔和眼睛反光一個圖層，眼白一個圖層，眉毛一個圖層等。

Live2D軟體允許創作者將這些圖層與網格(mesh)模型關聯，並根據參數對網格變形。 Live2D軟體允許創作者創建動作文件決定隨時間變化的參數，以及表情文件控制角色表情變化。

集成在Ren’Py中的Live2D系統可以使用對應的文件並顯示文件內定義的動畫。Ren’Py會根據具體參數值處理動作和表情。這些參數實際上會傳給原生的Cubism SDK，Ren’Py得到的返回值是一個待顯示的網格(mesh)列表。 Ren’Py渲染這些網格之後，就實現了螢幕上的Live2D角色。

Ren’Py同時支持Cubism 3和Cubism 4格式的Live2D動畫，即這兩種格式的表情與動作播放。

Warning

x86_64的安卓平台不支持Live2D，因為對應平台缺乏某個動態連接庫(DLL)。這也表示在安卓模擬器和ChromeOS上運行可能會有問題。

Web平台也不支持Live2D。

在iOS平台安裝Live2D時，需要手工將靜態庫複製到自己的iOS項目中。

安裝Live2D link

使用Live2D之前，你需要下載和安裝原聲的Cubism SDK，下載連結為 Live2D 頁面。請注意，如果你的商業項目年收入達到了某個下限，將需要購買一個Live2D使用許可證。

下載完Live2D後，把 CubismSdkForNative-4-r.1.zip 文件放入Ren’Py的SDK目錄中，接著可以在Ren’Py啟動器中安裝。在啟動器中進入“設置”項，選擇“操作”標籤下的“安裝庫”，點擊“安裝 Live2D Cubism SDK for Native”。等待一段時間後，Live2D就安裝成功了。

啟用GL2選項 link

如果需要使用Live2D，需要啟用基於模型的渲染器。在遊戲項目的任意腳本中添加一行：

define config.gl2 = True

定義動畫 link

使用Live2D可是組件與image語句可以定義Live2D動畫：

Live2D(filename, zoom=None, top=0.0, base=1.0, height=1.0, alias={}, loop=False, fade=None, seamless=None, attribute_function=None, attribute_filter=None, update_function=None, **properties) link

該可是組件會播放一段Live2D動畫。

filename

該值應該是一個 model3.json 或 .exp3.json 文件，文件內定義了Live2D動畫參數。例如，“Resources/Hiyori/Hiyori.model3.json”。

zoom

若該值非None，應用一個縮放係數。對 top 和 base 生效。

top

圖像的頂部，用於指定圖像大小。該值是一個表示比例的小數，0.0表示圖像最上方，1.0表示圖像最下方。

base

圖像的底部，用於指定圖像大小。該值是一個表示比例的小數，0.0表示圖像最上方，1.0表示圖像最下方。該值也會用來作為默認錨點在y軸方向的值(yanchor)。

height

圖像最終縮放高度。該值是表示整個螢幕高度比例的小數。

loop

若為True則循環播放最後一個動作。否則不循環。

alias

一個字典型數據，用來儲存對應動作或表情的別名。

fade

True if motion fading should be enabled, False if motion fading should not be enabled, and None to use the value of _live2d_fade. 若為True則啟用動作淡入淡出，若為False則不啟用。若為None則使用配置項 _live2d_fade 的值。

nonexclusive

若該值非None，必須是一個非排他性表情名稱的列表。表情預設是排他性的，即每次只能顯示一個表情。若表情加入非排他性列表中，則可以同時顯示多個非排他性表情，並附加在某個排他性表情上。

seamless

該值決定是否啟用無縫循環。無縫循環可以避免單一動作循環時也出現淡入淡出。該值為True表示始終啟用無縫循環，False表示禁用無縫循環，也可以是一個循環動作的集合。

default_fade

預設的動作或表情淡出時間，單位為秒。所有Live2D動作的預設值為1.0，也可能出現不希望出現淡出的情況。可以先把該值設置為0.0，根據實際需要顯式賦值。

attribute_function

若該值非None，應該是一個函數，入參是一個屬性(attribute)元組，返回值是另一個屬性元組。該函數可用於更換顯示內容的屬性——前提是顯示的圖像中未使用該屬性。需要確保該值至少對應給定表情的某一個屬性。

attribute_filter

若該值非None，應該是一個函數，入參是一個屬性(attribute)元組，返回值是另一個屬性元組。該函數通常用於濾除可能衝突的非排他性屬性。屬性會按最近使用時間排序，從近到遠。當屬性發生衝突時，將採用最近使用過的屬性。

update_function

若該值非None，應該是一個函數，當前動作和表情修改參數並渲染成動畫後，將調用該函數。調用該函數時需要有兩個入參：

Live2D對象。
顯示時間，單位為秒。

該函數用於動態修改參數，方法是使用Live2D對象中的 blend_parameter 方法。該函數應該返回一個數值，單位為秒，表示可以再次調用前的時間間隔；也可以返回None，表示下次交互行為發生時再次調用。當可視組件重新渲染時，也可能調用該函數。

attribute_function 與 attribute_filter 間的差別是：前者用於用新屬性替換原來的某個屬性；後者用來解決屬性衝突，確保一組屬性中存在唯一真正可用。

只有 filename 是固定位置參數，其他參數都是關鍵字參數。

相同 filename 的Live2D對象擁有相同的 alias、fade、nonexclusive、seamless、default_fade、attribute_function、 attribute_filter 和 update_function 值。因此只要指定第一個指定使用 filename 的Live2D對象的這系列參數即可。

blend_parameter(name, blend, value, weight=1.0) link

該方法會以參數 value 值使用遮罩模式(blend)。在 update_function 以外無效果。

name: 此模型需要修改的參數名稱。
blend: 遮罩模式，應該是“Add”、“Multiplay”或“Overwrite”之一。
value: 使用遮罩時的不透明度數值。
weight: 介於0.0到1.0之間的浮點數，表示使用遮罩後的新值所占權重。

blend_opacity(name, blend, value, weight=1.0) link

該方法會以參數 value 值使用遮罩模式(blend)。在 update_function 以外無效果。

name: 此模型需要修改的參數名稱。
blend: 遮罩模式，應該是“Add”、“Multiplay”或“Overwrite”之一。
value: 使用遮罩時的不透明度數值。
weight: 介於0.0到1.0之間的浮點數，表示使用遮罩後的新值所占權重。

透過一個配置項可用於幫助debug源自 .model3.json 文件的動畫和表情問題：

define config.log_live2d_loading = False link: 若為True，啟動時將會動作和表情記錄到載入目錄中的log.txt文件中。

Live2D可視組件應使用image語句聲明：

image hiyori = Live2D("Resources/Hiyori", base=.6)

聲明時也可以定義屬性(attribute)。在使用相同角色定義不同的縮放時，這非常有用。

image hiyori close = Live2D("Resources/Hiyori", base=.6)
image hiyori far = Live2D("Resources/Hiyori", base=.9)

請注意，調用 Live2D()時，用戶的硬體設備可能會不支持初始化Live2D，整個項目可能卡在載入階段。類型的情況也會發生在Web平台的版本上。創建的遊戲應該可以在不支持Live2D的情況下運行，比如使用跳轉或替代方案：

init python:
    def MyLive2D(*args, fallback=Placeholder(text="不支持Live2D"), **kwargs):
        if renpy.has_live2d():
            return Live2D(*args, **kwargs)
        else:
            return fallback

image kobayashi = MyLive2D(...)
image eileen moving = MyLive2D(..., fallback="eileen happy")

使用動畫 link

顯示Live2D圖像的通用方法是使用show語句。在show語句後面添加屬性(attribute)即可播放對應的表情和動作。

樣例如下：

show natori exp_00 mtn_01
show hiyori m10
show hiyori m10 m01

這裡使用的是Cubism SDK中範例角色的動作名。Ren’Py會從Live2D文件中提取動作和表情的名稱，強制轉換為小寫字母。 model3.json檔案名相同如果動作或表情名稱的前綴與對應的model3.json檔案名相同，這個前綴和緊跟著的下劃線會刪除，剩下的部分作為屬性。 (例如，“Hiyori_Motion01”處理後的屬性是“motion01”。)

排他性表情最多只有一種，非排他性表情和動作可以有任意種。同時指定多個動作時，所有動作按順序播放，如果loop參數為True則循環最後一個動作。這樣就可以播放完任意表情後，接著播放一個默認待機動畫。同時指定多個動作時，同屬性名的動作只能出現一次，除非使用的是同一個動作的多個不同別名。

There are two special attributes null and still. The null attribute means that no exclusive expression file should be applied, giving the character’s default expression. The still motion stops all motion. 還有兩個特殊的屬性： null 和 still 。 null 屬性表示不使用任何排他性表情文件，給定角色的默認表情。 still 則會停止所有動作。

非排他性表情將始終存在，除非顯式移除：

show hiyori -wave

縮放 link

許多Live2D模型製作時使用了超高的解析度，直接使用會查出螢幕顯示範圍。為了適配這種情況，Ren’Py中有兩種方法縮小Live2D模型。

第一種方式是使用 zoom 參數。這可以直接設置一個模型的縮放值。使用 zoom 參數後，其他縮放相關的參數都會忽略。

另一種方法是，使用 top、base 和 height 參數。前兩個參數指定了圖像顯示範圍的上下限(與Ren’Py中的其他地方相同，0.0表示頂部，1.0表示底部)。使用這些參數後，會發生兩件事：

圖片縮放後，顯示區域介於 top and base 之間，height 表示螢幕高度的一個比例。
錨點會調整，使 base 正好位於螢幕底部。

When figuring out how to scale a Live2D animation, what I do first is adjust the base parameter until the right part of the animation is lined up with the bottom of the screen. Then: 關於如何縮放Live2D動畫的問題，我做的第一件事是調整 base 參數，使動畫的底部能夠在螢幕上顯示出來。然後再根據情況：

如果圖像太大，降低 height 的值，知道獲取合適的尺寸。
如果圖像太小，增加 top 的值，以減少圖像上端與螢幕之間的空白空間。

動作平滑過渡 link

Ren’Py支持Live2D動作平滑過渡。一般來說，當Ren’Py中切換動畫時使用硬切換——當前動作停止，新動作再開始。如果使用轉場(transition)，畫面上同時出現兩個動畫。

Live2D支持另一種模式，通過在不同參數之間計算插值，可以實現新舊動畫間的平滑過渡。設想某個角色將自己的手臂移動到某個位置，計算新舊動畫之間位置的插值後用於過渡，而不是使用dissolve方式切換。

動作平滑過渡使用 fade 參數進行控制。若該值為True，啟用動作平滑過渡；相反則使用硬切換。若該值為None，根據 _live2d_fade 配置項的值決定是否啟用：

_live2d_fade = True link: 若為True，Live2D動畫啟用動作平滑過渡。若為False，動畫間硬切換。

設置別名 link

alias 參數允許創作者為動作設置別名。例如：

image hiyori = Live2D("Resources/Hiyori", base=.6, aliases={"idle" : "m01"})

設置別名後可以這樣使用：

show hiyori idle

想過與這句相同：

show hiyori m01

循環與圖片預載入 link

當 loop 參數設置為True時，Ren’Py將循環播放Live2D的最後一個動畫。需要播放某個循環動畫是，很重要的一點是，添加一個0.2秒的暫停時間。這能給Ren’Py一些時間執行消耗較大的圖片預載入。(圖片預載入和讀取發生在不同時間情況，這也可以不是必要的。)