데이터 저장 및 로드 — 코드 샘플

설명

이 예제는 stingray.SaveSystem 인터페이스를 사용하여 런타임 데이터를 디스크의 파일에 저장하고 나중에 프로젝트로 다시 읽어들이는 방법을 보여 줍니다.

저장 및 로드 작업은 모두 하드 디스크에 액세스해야 하므로 속도가 느려질 수 있습니다. 따라서 저장 및 로드는 코드의 다음 줄이 계속 실행되는 동안 백그라운드에서 발생하는 비동기 작업입니다. 이러한 작업은 이후 프레임까지 실제로 종료되지 않을 것입니다. 따라서 데이터를 즉시 사용할 수 없습니다. stingray.SaveSystem으로 프레임마다 종료되었는지 다시 확인해야 합니다.

stingray.SaveSystem에서 일부 데이터를 저장하거나 로드하도록 요청할 때마다 특정 요청을 식별하는 토큰을 제공합니다. 요청한 후에는 stingray.SaveSystem.progress()를 호출하고 토큰을 전달하여 해당 요청의 상태를 포함하는 테이블을 얻을 수 있습니다. stingray.SaveSystem에서 데이터를 로드하도록 요청한 경우 상태 테이블에는 해당 .data 필드에 로드된 데이터도 포함됩니다.

저장 또는 로드 요청이 완료되고 상태 테이블에서 데이터를 읽은 경우 해당 요청에서 사용 중인 메모리를 지우기 위해 stingray.SaveSystem.close()를 호출하고 토큰을 전달해야 합니다.

이 단순화된 샘플에서는 9 및 0 키를 사용하여 각각 저장 및로드를 트리거합니다.

코드

-- cache tokens in variables that will persist to future frames
save_filename = "my_data_file"
save_token = nil
load_token = nil

-- this update code is taken from a `project.lua` file in one of the standard Stingray template projects that
-- uses the Appkit.
function Project.update(dt)

    -- some data to test our save and load code.
    -- replace this with your own data.
    local data_to_save = {
        string_field = "hello world!",
        table_field = {
            boolean_one = true,
            boolean_two = false
        }
        -- let's use a random number that gets re-generated each frame, so we can tell
        -- that we're loading the same data we last saved.
        number_field = stingray.Math.random(0,100),
    }

    -- translate error codes into something human-readable and log them.
    function handle_error(code)
        if save_progress.error == "STINGRAY_SAVEDATA_ERROR_MISSING" then
            print("The file you're looking for does not exist.")
        elseif save_progress.error == "STINGRAY_SAVEDATA_INVALID_FILENAME" then
            print("The filename you've asked for isn't valid on this platform.")
        elseif save_progress.error == "STINGRAY_SAVEDATA_IO_ERROR" then
            print("A disk error occurred reading or writing data.")
        elseif save_progress.error == "STINGRAY_SAVEDATA_BROKEN" then
            print("Your save data seems to be corrupted.")
        elseif save_progress.error == "STINGRAY_SAVEDATA_UNSUPPORTED_VERSION" then
            print("The data was saved using an older version of Stingray, and isn't compatible with this version.")
        end
    end

    -- this helper function checks the different states a progress token can have, and
    -- decides how to handle each one.
    function check_token(token)
        if token then
            local save_progress = stingray.SaveSystem.progress(token)
            if not save_progress then return end
            if save_progress.error then
                print("An error occurred in the save or load operation!")
                handle_error(save_progress.error)
            elseif save_progress.done then
                print("Completed.")
                stingray.SaveSystem.close(token)
                -- For load operations, we return the loaded data.
                -- For save operations, we return true to indicate the token has been cleared.
                return save_progress.data or true
            elseif save_progress.progress > 0 then
                local percentage = save_progress.progress * 100
                print(tostring(percentage) .. "% completed.")
            end
        end
        return false
    end

    -- when the project needs to save some data:
    -- if a save isn't already in progress, start one and get a token.
    if stingray.Keyboard.pressed(stingray.Keyboard.button_id("9")) and not save_token then
        save_token = stingray.SaveSystem.auto_save(save_filename, data_to_save)
        print("The saved random number is: " .. tostring(data_to_save.number_field))
    end
    -- if a save is currently in progress:
    if save_token then
        -- if the save operation is done, clear the cached token.
        if check_token(save_token) then save_token = nil end
    end

    -- when the project needs to load some data:
    -- if a load isn't already in progress, start one and get a token.
    if stingray.Keyboard.pressed(stingray.Keyboard.button_id("0")) and not load_token then
        load_token = stingray.SaveSystem.auto_load(save_filename)
    end
    -- if a load is currently in progress:
    if load_token then
        -- if the load operation is done
        local retrieved_data = check_token(load_token)
        if retrieved_data then
            -- clear the cached token
            load_token = nil
            -- and do something with the data read from the save file.
            -- replace this with your own code.
            print("Data retrieved.")
            print("String field: " .. retrieved_data.string_field)
            print("Number field: " .. tostring(retrieved_data.number_field))
            print("The number should match the last saved number shown in the console log.")
            print("Nested boolean field one: " .. tostring(retrieved_data.table_field.boolean_one))
            print("Nested boolean field two: " .. tostring(retrieved_data.table_field.boolean_two))
        end
    end

end