cs-event-client v0.3.0

CodeScape Event Client

A Vuex module to expose the CodeScape Event Socket in any Vue component.

Installation

npm i -s cs-event-client

Example Usage

Configuring the environment

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import store from './store';

createApp(App).use(store).mount('#app');

// store/index.js
import { createStore } from 'vuex';
import { getVuexSocket } from 'cs-event-client';

const websocketURL = 'ws://localhost:3000/ws/';

const vuexSocket = getVuexSocket(websocketURL);

export default createStore(vuexSocket);

If the component has its own, additional Vuex Store states, getters, mutations, actions, and modules, you can specify these using the .extend syntax:

// store/index.js
import { createStore } from 'vuex';
import { getVuexSocket } from 'cs-event-client';

const websocketURL = 'ws://localhost:3000/ws/';

const vuexSocket = getVuexSocket(websocketURL).extend({
    state: {
        customProp: [],
    },
    getters: {
        customGetter: () => 42, 
    },
    mutations: {
        customMutation: (state) => {
            state.customProp.push('data');
        },
    },
    actions: {
        customAction: ({ commit }) => {
            commit('customMutation');
        },
    },
});

export default createStore(vuexSocket);

More information about states, getters, mutations, actions, and modules can be found on the Vuex website.

If the Vue application you're making will be responding instantaneously to new events in the game, there is additional setup required.

Firstly, you'll need to use the codescapePlugin, which exposes the $csEvent global property (similar to this.$store, there is now this.$csEvent).

// main.js
import { createApp } from 'vue';
import { codescapePlugin } from 'cs-event-client';

import App from './App.vue';
import store from './store';

createApp(App)
    .use(store)
    .use(codescapePlugin)
    .mount('#app');

You'll also need to load the CodeScape mixin into the root Vue component (usually 'App.vue') which will watch for any activity in the Game.

// App.vue
<template>
    <router-view/>
</template>

<script>
import { codescapeMixin } from 'cs-event-client';

export default {
    mixins: [codescapeMixin],
};
</script>

Connecting to a game

Declaring or listening for events cannot be done until the application has been registered to a game. Registering to a game only needs to be done once per application instance using the 'registerGame' action. It can be called from any component.

registerGame will connect the Vue app to a given game's event stream. Notice that the second argument must be an object:

this.$store.dispatch('registerGame', { 
    gameID, debug 
});

gameID (string) specifies the unique ID for the game to connect to.

debug (boolean) if set to true, all messages received will be printed to the console as a debug message.

Example usage is below:

// components/Example.vue
export default {
    created() {
        this.$store.dispatch('registerGame', { 
            gameID: 'anything',
        });
    },
};

Declaring events

Declaring an event to the game server is also done via the Store using the 'declareEvent' action.

declareEvent will declare an event to the game stream the store is connected to.

this.$store.dispatch('declareEvent', { 
    ID, status 
});

ID (int) specifies the unique ID of the event that is being declared.

status (int) specifies the unique status code of the event that is being declared.

Listening for events

Listening for events can either be done via callback or checking for past events.

If real-time response to an event is preferred, you can register a function as a callback to a given event using the $csEvent.register method (providing you have connected the plugin and mixin as described above).

this.$csEvent.register(eventID, callbackFn);

eventID (int) specifies the unique ID of the event that is being watched for.

callbackFn (func) specifies the callback function to be executed when the chosen event occurs on the game stream. The status code of the event will be passed into this function as the first (and only) argument.

export default {
    created() {
        this.$csEvent.register(1, this.logEvent);
    },
    methods: {
        logEvent1(status) {
            console.log(status);
        },
    },
};

Alternatively, to see the current status of an event - or all of its previous statuses - the eventDirectory object is used to get information about events that have occurred in the game.

To access it from any component, link the component to the eventDirectory's store entry:

// components/Example.vue
import { mapGetters } from 'vuex';

export default {
    name: 'Example',
    computed: {
        ...mapGetters([
            'eventDirectory',
        ]),
    },
    methods: {
        accessEventDirectory() {
            return this.eventDirectory.getAllEventStatuses();
        },
    },
};

The eventDirectory has five methods:

eventHasOccurred(ID) will return a boolean indicating whether the event with ID has occurred (i.e. its status is != 0).

getEventStatus(ID) will return the latest event status for the event with ID.

getEventHistory(ID) will return a chronologically-ordered array of all event statuses that have occurred for the event with ID.

getAllEventStatuses() will return an object containing ID-status key-value pairs for all recorded events.

getAllEventHistories() will return an object containing ID-history key-value pairs for all recorded events.