mlg
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.3 • Public • Published

    MLG

    Bring genuine MLG experience to live websites. React to DOM events and play various MLG effects. Each experience is unique as it is tailor in accordance to users' actions.

    What is MLG?

    Adding MLG

    Use CDN link:

    TODO: Host it somewhere
    
    // index.tml
    <script src="link-to-cdn" />
    <script>
        Mlg.init(mlgConfig);
    </script>
    

    Download it from NPM

    npm i --save mlg
    
    // index.js
    import 'mlg';
    
    Mlg.init(mlgConfig);
    

    MLG is automatically added to the global scope and can be accessed as Mlg.

    Configuring MLG

    MLG experience has to be configured via MlgConfig. The main task of MlgConfig is to bind effects to certain events and elements. By default no effects are dispatched. Currently MLG captures events solely on body element;

    Simple config:

    const mlgConfig = {
        effects: {
            // Hit Marker effect will be played anytime a click event occurs anywhere
            'hit-marker': ['click'],
            // Wow effect will be played anytime a keydown or keyup occurs anywhere
            wow: ['keydown', 'keyup],
            // Air Horn effect will me payed only if change occurs on input of type password
            // or if submit event occurs on any element
            'air-horn': {
                change: 'input[type="password"]',
                submit: '*'
            },
            // etc...
        }
    
    };
    
    Mlg.init(mlgConfig);
    

    Larger config:

    Mlg.init({
        effects: {
            'hit-marker': {
                click: ':not([type="submit"])',
            },
            'air-horn': ['input'],
            'small-circle-explosion': {
                click: '[type="submit"], [type="submit"] *',
            },
            'elevator-music-stop': ['submit'],
            'rainbow-frog-screen-start': ['submit'],
            'rainbow-frog-screen-stop': ['click'],
            'barely-alive-dead-link-start': ['submit'],
            'barely-alive-dead-link-stop': ['click'],
            'rotating-rainbow-background-start': ['submit'],
            'rotating-rainbow-background-stop': ['click'],
            'sniper-quick-scope': {
                click: 'img',
            },
            'baby-its-triple': {
                click: 'h1',
            },
        },
    });
    
    

    General binding pattern is effect-name : event-name[] | biding-object where binding-object may be defined as map of event-name : DOMSelector

    Getting MLG Effect Pack

    By default MLG knows no effects. In order to play effects an effect pack has to be added. Currently there is only one effect pack MLG Basic Effects which is under construction.

    Adding existing MLG Effect Pack

    Use CDN link:

    TODO: Host it somewhere
    
    // index.tml
    <script src="link-to-cdn-mlg" />
    <script src="link-to-cdn-effect-pack" />
    

    When adding MLG Effect Pack using <script> tag, it has to be added after the tag that adds MLG itself. There is no requirement on adding the tag before tag with Mlg.init. New effects can be added dynamically during MLG's lifetime.

    Download it from NPM

    npm i --save mlg-basic-effects
    
    // index.js
    import 'mlg';
    import 'mlg-basic-effects';
    
    Mlg.init(mlgConfig);
    

    The same rule applies to downloading from npm as mlg has to be imported before any effects.

    Creating custom MLG Effects

    You may want to create your own effects. Each effect is described by MlgEffectManifest which contains all important information about the effect. Effects should be agnostic to the event which invokes them. However, sometimes it cannot be done as for example effect that relies on cursor position can work only with mouse events.

    Sample manifest:

    {
        name: 'my-new-effect',
        effect: event => {
            /* do something */
        }
    }
    

    The effect function is the effect itself, where it's logic is hidden. It gets the captured event as an argument. The function is expected to return nothing (void) and can do almost anything. It's up to you to decide how you want to handle concurrency, manage your asset and delay the execution.

    When your manifest is ready it has to be registered. As Mlg is exposed globally (and MLG itself should be included before any effects) you can just call Mlg.registerEffect.

    Example no.1:

    // Simple effect that will play a sound
    const audio = new Audio(/*url to audio*/);
    
    Mlg.registerEffect({
        name: 'explosion',
        effect: () => {
            audio.play();
        }
    });
    

    Example no.2:

    // You can register the effects in promise chains
    const myAudioPromise = fetch(/*url to audio*/)
        .then(res => res.blob())
        .then(blob => URL.createObjectUrl(blob))
        .then(url => new Audio(url)).
        .then(audio => {
            Mlg.registerEffect({
                name: 'explosion',
                effect: () => {
                    audio.play();
                }
            });
        });
    
    

    Example no.3:

    // You may split your effect into two, one as a start and second as a stop.
    const audio = new Audio(/*url to some music*/);
    
    Mlg.registerEffect({
        name: 'song-start',
        effect: () => {
            audio.play();
        }
    });
    
    Mlg.registerEffect({
        name: 'song-strop',
        effect: () => {
            audio.stop();
        }
    });
    
    // These configuration will play the sound between onload event on body and first click
    {
        effects: {
            'song-start': {
                'onload': 'body'
            },
            'song-stop': ['click']
        }
    }
    

    Creating custom MLG Effect Packs

    Feel free to create your own packages of effects and share them via CDN or npm.

    TODO:

    • Custom dispatchers
      • Timer dispatchers - emit custom event after timeout
      • Reactive dispatchers - emit custom event after another event
    • Unregister effects
    • MLG can be initialized around other containers than body
    • Concurrent instances of MLG
    • Add support events to MlgEffectManifest to mitigate risk of broken effects
    • Create effect categories - combat code repetition in effect manifests.
    • Inject custom target element to the effect

    Keywords

    none

    Install

    npm i mlg

    DownloadsWeekly Downloads

    1

    Version

    0.0.3

    License

    MIT

    Unpacked Size

    12.5 kB

    Total Files

    4

    Last publish

    Collaborators

    • deathrage