Source code and scenarios in Winter Starfall

This tutorial contains instructions for downloading and running the source code for Winter Starfall, and a walkthrough of the code samples demonstrating best practices for login and purchase scenarios.

Source code download

Prerequisites

Install Node JS
Install Visual Studio Code

Setup for local development

Download the source code from GitHub.
In VS Code, open the /website folder and opt to install all the extensions it recommends.
In the /website directory, run npm install to install all dependencies.
Use npm run dev to start the site. Select the link it offers to view the site.

Azure credentials

To update the AZURE_CREDENTIALS secrets, run this command in the Azure Portal shell:

az ad sp create-for-rbac --name "VanguardOutrider2" --role contributor --scopes /subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP_NAME --json-auth

The player authentication flow in Winter Starfall has two steps: the login call and post-login functions that are used to get the player’s information from the service and load them into the correct location in the story.

Player authentication

For the login portion, the file use-login.ts defines a TypeScript wrapper function that handles the multiple authentication methods available to players. Lines 144-169 define the callback function for logging in with an email address, and call the post-login functions if login succeeds.

const onLogin = useCallback(() => {
    setIsLoading(true);
    setLoginMethodInProgress("email");

    dispatch(siteSlice.actions.loginSteps(loginEventCount));

    ClientLoginWithEmailAddress({ Email: data.email, Password: data.password })
        .then(result => {
            dispatch(siteSlice.actions.login(result));
            dispatch(siteSlice.actions.loginStepsAdvance());
            // Track logins from returning users
            trackEvent({ name: "Returning User", properties: {} });
        })
        .then(() => {
            return postLoginFunctions();
        })
        .then(() => {
            setIsLoading(false);
            navigate(routes.Explore());
        })
        .catch(problem => {
            dispatch(siteSlice.actions.loginStepsReset());
            onError(problem);
        })
        .finally(() => dispatch(siteSlice.actions.loginStepsReset()));
}, [ClientLoginWithEmailAddress, data.email, data.password, dispatch, navigate, onError, postLoginFunctions]);

The game offers 3 recoverable methods for player authentication: email, Google, and Facebook, so that player accounts will never be lost. For more information, see Login best practices. Once the security token has been retrieved, it is used to run the post login functions to get the saved game state. Lines 340-378 define postLoginFunctions, which calls various Economy and PlayFab Services APIs to load the correct story location, inventory items, currency, etc based on the player.

return new Promise<void>((resolve, reject) => {
    ClientGetTitleData({ Keys: TITLE_DATA_KEYS_ALL })
        .then(result => {
            dispatch(siteSlice.actions.titleData(result));
            dispatch(siteSlice.actions.loginStepsAdvance());
            loadScripts();
        })
        .then(() =>
            EconomySearchItems({
                Count: SEARCH_ITEMS_MAX_COUNT,
                Filter: "type eq 'currency' or type eq 'catalogItem'",
            })
        )
        .then(result => {
            dispatch(siteSlice.actions.catalog(result.Items));
            dispatch(siteSlice.actions.loginStepsAdvance());
        })
        .then(() => EconomyGetInventoryItems({ Count: SEARCH_ITEMS_MAX_COUNT }))
        .then(result => {
            dispatch(siteSlice.actions.inventory(result.Items));
            dispatch(siteSlice.actions.loginStepsAdvance());
        })
        .then(() => ClientGetUserData({ Keys: USER_DATA_KEYS_PLAYER_ALL }))
        .then(result => {
            dispatch(siteSlice.actions.userDataPlayer(result));
            dispatch(siteSlice.actions.loginStepsAdvance());
        })
        .then(() => ClientGetUserReadOnlyData({ Keys: USER_DATA_KEYS_READONLY_ALL }))
        .then(result => {
            dispatch(siteSlice.actions.userDataReadOnly(result));
            dispatch(siteSlice.actions.loginStepsAdvance());
        })
        .then(() => {
            resolve();
        })
        .catch(problem => {
            dispatch(siteSlice.actions.loginStepsReset());
            reject(problem);
        });
});

First ClientGetTitleData gets the secret key needed for all API calls
Then EconomySearchItems searches the catalog for currency and item types
Which is used as input to EconomyGetInventoryItems to return the player’s inventory items
Then ClientGetUserData retrieves the value that stores the story location as part of a player’s data.

Purchase flow

At certain points in the game, the player has the option to purchase and sell inventory items from the store. The purchase flow is implemented in another wrapper function. In the file use-store.ts, lines 40-69 bring up the correct store that the player encounters at a specific location and populates the items for sale by searching the catalog.

export function useEconomyStoreSingle(storeName: string): IEconomyStoreSingleResults {
    const dispatch = useDispatch();
    const store = useSelector((state: AppState) => state.site.stores).find(store =>
        store.AlternateIds?.find(friendlyId => friendlyId.Type === FRIENDLYID && friendlyId.Value === storeName)
    );
    const { isLoading, error, setError, EconomyGetItem } = usePlayFab();

    useEffect(() => {
        if (!is.null(store) || isStoreLoading) {
            return;
        }

        isStoreLoading = true;

        EconomyGetItem({
            AlternateId: { Type: FRIENDLYID, Value: storeName },
        })
            .then(results => {
                dispatch(siteSlice.actions.storeAdd(results.Item as PlayFabEconomyModels.CatalogItem));
            })
            .catch(setError)
            .finally(() => {
                isStoreLoading = false;
            });
    }, [EconomyGetItem, dispatch, setError, store, storeName]);

    return {
        error,
        isLoading,
        store,
    };
}

EconomyGetItem is defined in use-playfab.ts at lines 423-446, within which the PlayFab Economy API GetItems is used to search the catalog and return items.

const EconomyGetItems = useCallback(
        (request: PlayFabEconomyModels.GetItemsRequest): Promise<PlayFabEconomyModels.GetItemsResponse> => {
            const date = startRequest("EconomyApi", "GetItems", request);

            return new Promise((resolve, reject) => {
                PlayFab.EconomyApi.GetItems(request, (result, problem) => {
                    endRequest(date, problem, result);

                    if (!is.null(problem)) {
                        return reject(problem);
                    }

                    if (result.code !== 200) {
                        return reject(formatPlayFabNon200Error(result));
                    }

                    return resolve(result.data);
                }).catch(reason => {
                    catchRequest(reject, reason);
                });
            });
        },
        [catchRequest, endRequest, startRequest]
    );

When a purchase is conducted, a call to the PurchaseInventoryItems API is made. This is defined in use-playfab.ts at lines 540-565.

Selling items

The selling flow is an example of how to use Azure Functions driven CloudScript to extend the functionality of the Economy system. SellItem.cs defines the CloudScript function that executes when selling an item. Lines 49-61 are where PlayFab’s GetTitleData API is used to return the store multiplier and calculate the sale price.

 // Get your sell multiplier
var titleData = await PlayFabFunctions.GetTitleDataAsync(player, new List<string> { TitleDataKeys.Multipliers }, log);
var sellMultiplier = JsonConvert.DeserializeObject<Multipliers>(titleData[TitleDataKeys.Multipliers])?.sell ?? 1;

The CloudScript function then gets called in lines 161-187 of use-store.ts.

export function useEconomyStoreSell(): IEconomyStoreSellItemResults {
    const { isLoading, error, setError, CloudScriptExecuteFunction, EconomyGetInventoryItems } = usePlayFab();
    const dispatch = useDispatch();

    const onSell = useCallback(
        (itemId: string, amount: number) => {
            return new Promise<void>((resolve, reject) => {
                CloudScriptExecuteFunction({
                    FunctionName: "SellItem",
                    FunctionParameter: {
                        ItemId: itemId,
                        Amount: amount,
                    },
                })
                    .then(() => EconomyGetInventoryItems({ Count: SEARCH_ITEMS_MAX_COUNT }))
                    .then(data => {
                        dispatch(siteSlice.actions.inventory(data.Items));
                        resolve();
                    })
                    .catch(issue => {
                        setError(issue);
                        reject(issue);
                    });
            });
        },
        [CloudScriptExecuteFunction, EconomyGetInventoryItems, dispatch, setError]
    );

To run Winter Starfall locally you’ll need an Azure account to support the CloudScript functions. You can sign up for a free Azure account and then follow the instructions above to reset the Azure credentials correctly.

XBOX Services

PlayFab

Source code and best practices - Winter Starfall

Source code and scenarios in Winter Starfall

Source code download

Prerequisites

Setup for local development

Azure credentials

Player authentication

Purchase flow

Selling items

See also

​Source code and scenarios in Winter Starfall

​Source code download

​Prerequisites

​Setup for local development

​Azure credentials

​Login flow

​Player authentication

​Post login: Getting player data

​Purchase flow

​Selling items

​See also

Source code and scenarios in Winter Starfall

Source code download

Prerequisites

Setup for local development

Azure credentials

Login flow

Player authentication

Post login: Getting player data

Purchase flow

Selling items

See also