====== Hệ Thống Tiền Tệ Tùy Chỉnh ======
{{:script:feature:custom_currency_script.png?direct&400|}}\\
Đây là hướng dẫn tạo hệ thống tiền tệ tùy chỉnh dành cho nhà phát triển bản đồ bằng cách sử dụng script đơn giản.\\

===== 👉 Yêu Cầu =====
  * **Bạn sẽ cần một Biến Trigger để lưu trữ tiền tệ của người chơi.**
{{:script:feature:string_group_currency_data.png?direct&400|}}
<WRAP center round important 100%>
QUAN TRỌNG! Phải sử dụng cùng một tên với biến trong script, đó là **“CURRENCY_DATA”** (dạng biến nhóm chuỗi riêng tư).
</WRAP>
Để bật tính năng lưu dữ liệu người chơi, Bạn có thể dễ dàng bật Upload **Cloud Variable**.\\

===== Tạo Khung Hệ Thống (Framework) =====
{{:script:feature:script_ui_location.png?direct&400|}}
Tôi khuyên nên đặt đoạn script này vào UI Script, vì Bạn sẽ sử dụng UI Cửa Hàng, UI Phần Thưởng, v.v... Điều này sẽ giúp việc xử lý tiền tệ dễ dàng hơn khi dùng khung hệ thống này.\\

==== Bước 1: Tạo Biến TOÀN CỤC (GLOBAL) ====
  * Biến toàn cục được khai báo không sử dụng tiền tố “local”.
  * Biến toàn cục có thể được gọi ở bất cứ đâu trong cùng thư mục.
  * **UI Script và Global Script là hai mục khác nhau, nên chúng không chia sẻ cùng biến toàn cục.**
Hãy sử dụng một tên dễ nhớ, ví dụ như **“GLOBAL_CURRENCY”**. Và đây là 2 dòng code đầu tiên của Bạn sẽ trông như thế này.\\
<code lua>
GLOBAL_CURRENCY = {} -- Initiate The Currency Global Table to Store Function and Methods..
GLOBAL_CURRENCY.DATA = {} --Table to Store Currency Data.
</code>

==== Bước 2: Tạo Hàm Phương Thức (Methods Function) ====
**Tạo Phương Thức Tiền Tệ (Currency Method)**\\
Đây là phương thức để tạo loại tiền tệ và lưu trữ nó. Dưới đây là phần giải thích cho từng tham số:\\
  * **name** là kiểu string – đây là nơi bạn đặt tên cho loại tiền tệ.
  * **id** là kiểu number – và phải sử dụng chỉ số Lua cơ bản (giống như chỉ số trong bảng – table).
  * **description** là kiểu string – đề phòng trường hợp bạn muốn có phần mô tả cho loại tiền tệ.
  * **type** là kiểu string.
<code lua>
function GLOBAL_CURRENCY:CreateCurrency(name, id , description , type)
    -- initiate new Table with exact Name of  Currency and store its id, description and type
    self.DATA[name] = {name=name,id=id,description=description,type=type}
end 
</code>

----

**Phương thức lấy tiền tệ của người chơi**\\
Phương thức này dùng để lấy dữ liệu tiền tệ của người chơi thông qua tên loại tiền tệ.\\
<code lua>
function GLOBAL_CURRENCY:GetCurrency(playerid,name)
    -- String Group 
    local r,datas = Valuegroup:getAllGroupItem(18, "CURRENCY_DATA",playerid)
    if r == 1001 then 
        Player:notifyGameInfo2Self(playerid,"CURRENCY DATA NOT FOUND!")
    end 
    return datas[GLOBAL_CURRENCY.DATA[name].id] or 0;
end 
</code>

----
**Phương thức hiển thị số tiền tệ đẹp mắt**\\
Chuyển đổi số thành chuỗi có thể hiển thị trên UI và trông ngắn gọn, dễ nhìn.\\
Ví dụ: 1000 sẽ thành “1k”.\\
<code lua>
function GLOBAL_CURRENCY:PrettyDisplay(amount)
    amount = tonumber(amount)
    local formatted = ""
    if amount >= 1e12 then
        formatted = string.format("%.1fT", amount / 1e12) -- Display in Trillions
    elseif amount >= 1e9 then
        formatted = string.format("%.1fB", amount / 1e9) -- Display in Billions
    elseif amount >= 1e6 then
        formatted = string.format("%.1fM", amount / 1e6) -- Display in Millions
    elseif amount >= 1e3 then
        formatted = string.format("%.1fk", amount / 1e3) -- Display in Thousands
    else
        formatted = tostring(amount) -- If less than 1000, display the full amount
    end
    return formatted
end
</code>

----
**Phương thức cập nhật UI**
Phương thức này dùng để xử lý việc cập nhật giao diện khi tiền tệ của người chơi được sử dụng hoặc nhận thêm.\\
<code lua>
-- Store UI_Data inside GLOBAL_CURRENCY
GLOBAL_CURRENCY.UI_DATA={}
 
-- This is Tell What UI element should be updated when calling UpdateUI for player
function GLOBAL_CURRENCY:AddUI2Update(name,uiid,elementid)
    if GLOBAL_CURRENCY.UI_DATA[name] == nil then 
        -- initiate an Empty table if it is nil
        GLOBAL_CURRENCY.UI_DATA[name] = {}
    end 
    table.insert(GLOBAL_CURRENCY.UI_DATA[name],{uiid=uiid,elementid=elementid});
end
 
-- Can Be Called  from any UI element to update the UI
function GLOBAL_CURRENCY:UpdateUI(playerid,name)
    if GLOBAL_CURRENCY.UI_DATA[name] == nil then 
        print("FAILED TO UPDATE UI : NO ELEMENTID WERE ADDED")
        return false 
    end 
    local ammountPretty = GLOBAL_CURRENCY:PrettyDisplay(GLOBAL_CURRENCY:GetCurrency(playerid,name))
    for i,a in ipairs(GLOBAL_CURRENCY.UI_DATA[name]) do
        Customui:setText(playerid,a.uiid,a.elementid,ammountPretty)
    end 
end
</code>

----
**Phương thức chỉnh sửa tiền tệ của người chơi**\\
**Thêm tiền cho người chơi** Khi sử dụng hàm này, bạn có thể cần xác thực thời gian để tránh bị khai thác lỗi hoặc bug.\\
  * __playerid:__ là số UID của người chơi.
  * __name:__ là tên loại tiền tệ.
  * __v_ammount:__ là số lượng tiền tệ muốn thêm.
<code lua>
function GLOBAL_CURRENCY:AddCurrency(playerid, name, v_ammount)
    -- Get Player Data 
    local ammount = GLOBAL_CURRENCY:GetCurrency(playerid,name)
    -- handle if ammount is empty 
    if ammount == nil then
        -- Player currency is not set Yet !
        ammount = 0 
    end 
    if type(ammount) == "String" then 
        ammount = tonumber(ammount);
    end 
    ammount = ammount + v_ammount;
 
    local id = GLOBAL_CURRENCY.DATA[name].id;
    -- Add Amount to Player Data
    local r = Valuegroup:setValueNoByName(18, "CURRENCY_DATA", id, tostring(ammount), playerid)
    if r == 0 then 
        -- Automatically Update all UI for player 
        GLOBAL_CURRENCY:UpdateUI(playerid,name)
        return  true;
    else 
        print("ERROR WHEN TRYING TO ADD CURRENCY TO PLAYER DATA")
        return false;
    end 
end
</code>

----
**Giảm tiền của người chơi**\\
Phương thức này cho phép số tiền của người chơi có thể giảm xuống dưới 0.\\
  * __playerid:__ là số UID của người chơi.
  * __name:__ là tên loại tiền tệ.
  * __v_ammount:__ là số tiền tệ muốn giảm.
<code lua>
function GLOBAL_CURRENCY:DecreaseCurrency(playerid, name, v_ammount)
    -- Get Player Data 
    local ammount = GLOBAL_CURRENCY:GetCurrency(playerid,name)
    -- handle if ammount is empty 
    if ammount == nil then
        -- Player currency is not set Yet ! 
        ammount = 0 
    end 
    if type(ammount) == "String" then 
        ammount = tonumber(ammount);
    end 
    ammount = ammount - v_ammount;
 
    local id = GLOBAL_CURRENCY.DATA[name].id;
    -- Add Amount to Player Data
    local r = Valuegroup:setValueNoByName(18, "CURRENCY_DATA", id, tostring(ammount), playerid)
    if r == 0 then 
        -- Automatically Update All UI for player
        GLOBAL_CURRENCY:UpdateUI(playerid,name)
        return true 
    else 
        print("ERROR WHEN TRYING TO DECREASE VALUE ON PLAYER SAVE CURRENCY_DATA")
        return false
    end 
end 
</code>

----
**Tiêu tiền của người chơi**\\
Kiểm tra xem người chơi có đủ tiền để tiêu hay không. Trả về false nếu không đủ tiền để tiêu. Giảm tiền tệ và trả về true nếu đủ tiền để tiêu.\\
  * __playerid:__ là số UID của người chơi.
  * __name:__ là tên loại tiền tệ.
  * __v_ammount:__ là số tiền tệ muốn tiêu.
<code lua>
function GLOBAL_CURRENCY:SpendCurrency(playerid, name, v_ammount)
    -- Get Player Data 
    local ammount = GLOBAL_CURRENCY:GetCurrency(playerid,name)
    -- handle if ammount is empty 
    if ammount == nil then
        -- Player currency is not set Yet
        ammount = 0 
    end 
    if type(ammount) == "String" then 
        ammount = tonumber(ammount);
    end 
    ammount = ammount - v_ammount;
    if ammount >= 0 then 
    local id = GLOBAL_CURRENCY.DATA[name].id;
    -- Add Amount to Player Data
    local r = Valuegroup:setValueNoByName(18, "CURRENCY_DATA", id, tostring(ammount), playerid)
        if r == 0 then 
            -- Automatically Update All UI for player
            GLOBAL_CURRENCY:UpdateUI(playerid,name)
            return true 
        else 
            print("ERROR WHEN TRYING TO UPDATE VALUE ON PLAYER SAVE CURRENCY_DATA")
            return false
        end 
    else 
        Player:notifyGameInfo2Self(playerid,"Not Enough "..name.." Need "..ammount.." of "..name);
        return false;
    end 
end
</code>

----
**Ví dụ cách sử dụng**\\
**Tạo loại tiền tệ**\\
Tạo loại tiền tệ đầu tiên với tên là “Coin”, và mô tả là: Loại tiền được dùng để mua vật phẩm trong game và cửa hàng. Có thể nhận miễn phí hoặc nạp thẻ. Loại (type) là “C”, tức là biến tùy chỉnh mà bạn có thể sử dụng sau này.\\
<code lua>
GLOBAL_CURRENCY:CreateCurrency(
    "Coin",1,
    [[Currency That is Used for Ingame Items and Shop, Can Be Obtained for Free or Via Top Up]],
    "C")
</code>

----
**Đăng ký phần tử UI để cập nhật khi tiền tệ thay đổi**\\
Ví dụ về cách thêm phần tử UI để được cập nhật mỗi khi tiền tệ thay đổi, và cập nhật UI khi người chơi vào game.\\
{{:script:feature:adding_ui_to_update.png?direct&800|}}

----
**Ví dụ sử dụng với Shop UI Script**\\
Giao diện Shop UI rất dài và phức tạp, nhưng đây là đoạn mã ví dụ ngắn về cách triển khai.\\
{{:script:feature:shop_ui_lua.png?direct&800|}}

----