A little demo using crank inside of a dotnet core game

[monodop]

Hey, been a while since I've posted on here. I made a little demo where I built a game in .net core, and used the Chromium Embedded Framework (CEF) to host a web app inside for all of the user interface elements (which are of course written in Crank). The benefit of doing this is that you can build your game in whatever language or engine you want (including unity or unreal - but this demo isn't made in any particular game engine), while still being able to take advantage of the millions of hours of development that went into building modern web technologies and developer tooling. Now I don't have to deal with stupid, limited UI frameworks 😉

For various reasons, I can't post the entire source code here, but I did want to post a demo video here: https://www.youtube.com/watch?v=R2NmEFjEyhQ

Thank you to @brainkim and everyone else who has contributed to Crank. This has been a fun project so far and crank has made the process of prototyping this super easy!

[brainkim]

This is cool! I always wonder why more indie games aren’t made with web tech; like almost all card games could be DOM based with a little bit of work. Lemme know if you have any feedback or would like any help with anything!

[monodop]

Yeah I wish the technique would be picked up by one of the big engines, but for now I think it's a lot more difficult of a programming task than I think most indie devs are able to deal with in a reasonable amount of time. The technologies that do exist to do this are pretty difficult to understand and don't have very good documentation. I know in the past some people were using https://github.com/libRocket/libRocket, but that's not exactly a full web browser.

There's also some big game studio options that use a similar technology - the kind where if you have to ask what the price is then you aren't a big enough studio. Things like https://coherent-labs.com/products/coherent-gameface/

I also stumbled upon this today https://gpl.ea.com/eawebkit.html. I guess most of EA games use this technology.

The cool thing about this is that you can use this in conjunction with normal game techniques & engines. The web ui is just an overlay for all the the interface components, menus, etc, but you can still use your engine of choice to handle everything else, like rendering 3D, physics, effects, etc.

As for feedback, the UI isn't terribly complicated. I've implemented a message bus between the backend game and the ui, so I can send RPC-style commands as well as broadcast events to listen to. All I have to do is subscribe to the message bus inside the crank component and yield new dom elements whenever that happens. Seems like a pretty natural way to use crank.

Edit: another one: https://ultralig.ht/

[monodop]

Here's a code snippet for one of the ui components if you're interested:

import { createElement, Context } from '@bikeshaving/crank';
import { css, StyleSheet } from 'aphrodite';
import { InventoryResponse, InventoryUpdatedEvent, InventorySlotSelectedEvent, Item } from '../../events/InventoryEvents';
import { MessageBus } from '../../MessageBus';
import { InventorySlot } from './InventorySlot';

export type InventoryProps = {
    name: string;
    allowSlotSelection?: boolean;
    imageGhosts?: string[];
};

export async function* Inventory(this: Context, {name, allowSlotSelection = false}: InventoryProps) {
    let inventory: InventoryResponse = {
        InventoryName: name,
        Items: [],
        Size: 0,
        SelectedSlot: 0,
    }

    this.cleanup(MessageBus.SubscribeBroadcastByKey<InventoryUpdatedEvent>("inventory.updated", (ev) => {
        if (ev.InventoryName === name) {
            console.log(`inventory ${name} updated`, JSON.stringify(ev));
            inventory.Items[ev.Slot] = ev.Item;
            this.refresh();
        }
    }));
    this.cleanup(MessageBus.SubscribeBroadcastByKey<InventorySlotSelectedEvent>("inventory.slot-selected", (ev) => {
        if (ev.InventoryName === name) {
            console.log(`slot selected in ${name}`, JSON.stringify(ev));
            inventory.SelectedSlot = ev.Slot;
            this.refresh();
        }
    }));
    let onSlotClick = (slot: number, item: Item | null) => {
        MessageBus.SendBroadcast("inventory.request-slot-selected", {
            InventoryName: name,
            Slot: slot,
        });
    };
    inventory = await MessageBus.SendRpcAsync<InventoryResponse>("inventory", {
        InventoryName: name,
    });
    console.log(`inventory status ${name}`, JSON.stringify(inventory));

    try {
        for await (let {imageGhosts} of this) {
            yield (
                <div class={css(styles.hotbarContainer)}>
                    {inventory.Items.map((item, slot) => (
                        <InventorySlot
                            crank-key={slot}
                            itemDefinition={item?.Definition}
                            inventoryName={name}
                            slot={slot}
                            image={item?.Definition.Icon}
                            imageGhost={(imageGhosts || [])[slot]}
                            quantity={item?.Quantity}
                            selected={allowSlotSelection && slot === inventory.SelectedSlot}
                            onClick={allowSlotSelection ? () => onSlotClick(slot, item) : undefined}
                            draggable={true}
                            />
                    ))}
                </div>
            );
        }
    }
    catch (e) {
        console.error(e);
    }
}

let styles = StyleSheet.create({
    hotbarContainer: {
        display: 'grid',
        gridTemplateColumns: 'repeat(10, 1fr)',
        gridGap: '0.2em',
        backgroundColor: '#444',
        padding: '0.3em',
        borderBottom: '0',
    }
});

[mcjazzyfunky]

Thank you very much @monodop for sharing your code. I think it's quite important that the Crank community shares as much real-world code (or at least code patterns) as possible to evolve and evaluate useful cranky design patterns. Real-world examples are way better for that than just simple demos.

Please allow me to be a bit annoying now. Actually it's about a special bug pattern that I've seen in a lot of non-trivial Crank components. I say "annoying" because I've already mentioned that problem at least a half-dozen times (in other issues/discussions) and frankly each time I was under the impression that everybody just thought "What the hell is that guy talking about?!?" or at least preferred to ignore that issue completely, but actually it's pretty obvious (I guess that will actually not be a problem in your app but nevertheless it's a bug): The component Inventory will only use the initial values for the props name and allowSlotSelection. If the property name changes over time the new inventory data will not be loaded. If the property allowSlotSelection changes over time it will not effect the ouput (will just rerender the old output). The prop imageGhosts is the only one that's handled properly.

The most interesting case for a fixed version of the Inventory component is the following:
The component Inventory has been loaded completely. One minute later, the parent component changes prop name so the new inventory data has to be loaded. While the data is loading (let's say it takes some time) the props allowSlotSelection or imageGhosts changes - what's happening? (=> should rerender with the new props, while the new inventory data is still loading).
Another interesting case for a fixed version of the Inventory component is that the component is loaded properly and one minute later the parent component changes one of the props allowSlotSelection or imageGhosts then the component should be rerendered with the new props but without reloading the inventory data.
My claim is that if you fix all the above mentioned issues with component Inventory then it will turn out that you will not use an async generator any longer (as it will block while loading new inventory data), which is IMHO quite interesting as using asyn generators (which are a big advantage of Crank) will not be a big help for this component any longer.
Also quite interesting IMHO is that in React (using some usePromise(...) hook with a dependency array) you would not have the above mentioned issues in the first place (I've already mentioned that somewhere else - maybe not that important).

[monodop]

Yeah I was aware of that case when writing this code, but I don't think I'll be running into it with the way that this component is used.. for now. Mainly I just wanted to get stuff working. You're totally right though though. If the inventory name or allowSlotSelection changes, you're probably looking at a brand new inventory, and you'd need to pull that inventory from the game from scratch and reupdate the subscriptions - basically the same as doing a full unmount and remount - but the parent components that call this will never change these values in their lifetime. I did leave imageGhosts as a property inside the main loop as this property is likely to change over time.

I'd be interested to see how you might write this component though. As the ui grows on this project, I'm definitely going to be running into more of those types of cases and I don't have a great pattern to solve it figured out yet. I've been a bit inactive here so maybe there's something built in to help solve this. Otherwise I'm stuck with my old "check the previous value against the new value" technique inside the loop, but I really hate that approach :(

[mcjazzyfunky]

@monodop

I don't think I'll be running into it with the way that this component is used.

I think we agree, that this Inventory component is extremely special and I really do not have problems if this very special component (which will only be use in one very special use case) does know about (quote) "the way [it] is used". What I've written above is more about this bug pattern in general.
Hopefully we also agree that in general a component should (at least in most cases) not know anything (or at least: not too much) about the way it is used. If you write a function in whatever programming language, this function normally does not know where it will be called or how often or by whom it will be called etc. Why should it be different with component functions (except maybe for some provision stuff)?

I'd be interested to see how you might write this component though.

Frankly, I really have no clue at all. The only solution that I have, will look tooooo React-like and this pattern has already been discussed and it has been decided that this should NOT be used in Crank.
And frankly, since months I'm waiting to see a snippet of crank code that provides a crank conform solution for that, but I have never seen one.

Just for your information, what I've meant looks like follows, but like said, this is NOT an option in Crank (be aware that this usePromise function may look like React hooks, but it is only called once per component instance and it has this as argument, so just a very normal effectful function - no hook magic or something):

// This is just for information - DON'T USE THAT PATTERN!!!

function* Inventory(props) {
  ...
  // THE FOLLOWING SHOULD NOT BE DONE IN CRANK!!!!  
  const loader = usePromise(this,
    () => loadInventoryData(props.name),
    () => [props.name])
  ...

  for (props of this) {
    if (loader.isPending()) {
      yield ...
    } else if (loader.isRejected()) {
      ...
      ... loader.getError() ...
      ...
      yield ...
    } else { // => isResolved
      ...
      ... loader.getResult() ...  
      ...
      yield ...
    }
  }
}

[monodop]

I think this solution seems to work. It's a little finicky though.

To test, I set the parent to automatically toggle between two different inventories. Before the fix:

After the fix:

Some notable things:

• I was able to get it mostly working by just moving the await into the loop, but I had to add a prev!==current check to avoid unnecessary calls.
• The subscriptions to check for updates need to check prev===current in order to ensure that an update isn't processed while the data is being re-fetched.
• Managing variables is a pain, because the name in the function parameters is a different name than the one coming from the props in the loop. Avoiding using name for any of the state variable names seems to help
• The changes only solve the name issue. The allowSlotSelectionIssue still has to be solved, but I think the fix is trivial at this point.

I feel like there ought to be a better way to deal with this.

import { createElement, Context } from '@bikeshaving/crank';
import { css, StyleSheet } from 'aphrodite';
import { InventoryResponse, InventoryUpdatedEvent, InventorySlotSelectedEvent, Item } from '../../events/InventoryEvents';
import { MessageBus } from '../../MessageBus';
import { InventorySlot } from './InventorySlot';

export type InventoryProps = {
    name: string;
    allowSlotSelection?: boolean;
    imageGhosts?: string[];
};

export async function* Inventory(this: Context, {name, allowSlotSelection = false}: InventoryProps) {
    let inventory: InventoryResponse = {
        InventoryName: name,
        Items: [],
        Size: 0,
        SelectedSlot: 0,
    };
    let currentName: string = name;
    let prevName: string = "";

    this.cleanup(MessageBus.SubscribeBroadcastByKey<InventoryUpdatedEvent>("inventory.updated", (ev) => {
        if (ev.InventoryName === currentName && prevName === currentName) {
            console.log(`inventory ${currentName} updated`, JSON.stringify(ev));
            inventory.Items[ev.Slot] = ev.Item;
            this.refresh();
        }
    }));
    this.cleanup(MessageBus.SubscribeBroadcastByKey<InventorySlotSelectedEvent>("inventory.slot-selected", (ev) => {
        if (ev.InventoryName === currentName && prevName === currentName) {
            console.log(`slot selected in ${currentName}`, JSON.stringify(ev));
            inventory.SelectedSlot = ev.Slot;
            this.refresh();
        }
    }));
    let onSlotClick = (slot: number, item: Item | null) => {
        MessageBus.SendBroadcast("inventory.request-slot-selected", {
            InventoryName: currentName,
            Slot: slot,
        });
    };

    try {
        for await (let {imageGhosts, name} of this) {
            currentName = name;
            if (prevName !== currentName) {
                inventory = await MessageBus.SendRpcAsync<InventoryResponse>("inventory", {
                    InventoryName: currentName,
                });
                prevName = currentName;
                console.log(`inventory status ${currentName}`, JSON.stringify(inventory));
            }
            yield (
                <div class={css(styles.hotbarContainer)}>
                    {inventory.Items.map((item, slot) => (
                        <InventorySlot
                            crank-key={slot}
                            itemDefinition={item?.Definition}
                            inventoryName={currentName}
                            slot={slot}
                            image={item?.Definition.Icon}
                            imageGhost={(imageGhosts || [])[slot]}
                            quantity={item?.Quantity}
                            selected={allowSlotSelection && slot === inventory.SelectedSlot}
                            onClick={allowSlotSelection ? () => onSlotClick(slot, item) : undefined}
                            draggable={true}
                            />
                    ))}
                </div>
            );
        }
    }
    catch (e) {
        console.error(e);
    }
}

let styles = StyleSheet.create({
    hotbarContainer: {
        display: 'grid',
        gridTemplateColumns: 'repeat(10, 1fr)',
        gridGap: '0.2em',
        backgroundColor: '#444',
        padding: '0.3em',
        borderBottom: '0',
    }
});

[mcjazzyfunky]

The problem is still that inventory = await MessageBus.SendRpcAsync... will block the whole component for the time of loading new inventory data and a component update in this loading time will not be possible. Means if the parent component updates prop allowSlotSelection or prop imageGhosts while the component is currently loading inventory data, no actual update will be performed before the end of that inventory loading.
Guess this is not a problem in your special use case but it will be a problem with async generator components in general.

Actually, I was happy that Dan (I think it's not very polite to write people's full name on the internet - sure you know who I mean => he's a Top-3 React expert) wrote the following a couple of days ago on Twitter (so it seems that I am not the only person who sees a challenge here):
"[...] interested in how it handles concrete cases, like editing an input in the same component after an async transaction has already started"
This is exactly what's the problem with async generator components in Crank => they just block while "await"ing for data.
That's why I've written somewhere above: "My claim is that if you fix all the above mentioned issues with component Inventory then it will turn out that you will not use an async generator any longer".

Oh, btw: I've written somewhere above "Frankly, I really have no clue at all" (about how to implement that). I guess I could find a way how to implement that (by using a normal generator function), but I do not now how to implement it in a way that is not a complete PITA (without using this above mentioned uncranky usePromise helper function or something similar).

[mcjazzyfunky]

🤷‍♀️

[mcjazzyfunky]

[EDIT: Seems that the comments which the following is referring to are gone ... just fyi]

it's still technically an async generator but I'm getting your point about it might as well not being one

Ah yeah, of course I was wrong or at least really unprecise here. It's more like: await loadSomeData(...) blocks, and if you do not want your components to block while loading, you may not use await for the loading promise but use loadSomeData(...).then(...).catch(...) instead (that does of course not necessarily mean that you have to switch to a normal generator function). Then the question is, what do you need an async generator for in such cases? One answer could be to have more control regarding lifecycle as async generators support all life-cycle events out of the box AFAIK (even without this.schedule(...) and this.cleanup(...)) while a "normal" generator function component does not.

Oh oof I think this fails if the props change again during the loading.

Actually, I think for this discussion it's not necessarily important that everything is working 100% fine, it was more important to me to point out that there might be some pitfalls with async components which are often not considered in concrete crank component implementations. Statements like "async components are damn easy with crank as you can just use async generators and everything is easy-peasy then" may just not be 100% true - that's all I wanna say. And I also always ask myself (already asked that in some other issues/discussions) how it will be possible to get rid of boilerplate code without using helper functions that have the context (aka. this) as argument, which automatically would lead to something that looks a bit more react-like (I guess most folks in the crank community do not have problems with such boilerplate code as it is "just JavaScript" and "transparent" - but frankly, this is (I've mentioned it several times in the last couple of month) the complete opposite of my own opinion).

[brainkim]

I see these comments and hope to read through and respond to this stuff more thoroughly soon! If you see concrete bugs, feel free to open an issue. I agree with most of what @mcjazzyfunky says. If you’re experiencing difficulty, I recommend maybe writing the logic you want with manual callbacks first using a sync generator component, just so that you understand what’s going on without having to deal with async generators. I think one thing I may have communicated poorly is to highlight async generator components in the initial blog post as the be-all end-all. This was the initial motivation for writing Crank, but as I use it more and more, I realize that the main use case for async generators is as a way to race renderings in the tree in Suspense-like fashion, or to consume async iterators which you have already defined elsewhere.

The reality is is that async generator functions have lots of subtle difficulties. It combines both the difficulties of using await and the difficulties of using yield in a single scope, and it’s almost impossible, for instance, to reason about whether your async generator is suspended on a yield or an await. Crank would have been a more or less capable framework if I had only implemented the sync function and sync generator components, and the fact that they render exactly synchronously makes development so much easier.

That said, I hope to improve the async generator story soon. I have an async iterator combinator library in the works, which might help us do stuff that looks a little more like FRP.

[brainkim]

Also, I discovered some rendering bugs related to async generator components which I literally just fixed yesterday, while trying to come up with some examples to respond to a twitter thread. My bad! If you’re having trouble I suggest upgrading and seeing if that fixes anything, otherwise please do file a bug report. Or not, you are free to do as you please!

[monodop]

I think one thing I may have communicated poorly is to highlight async generator components in the initial blog post as the be-all end-all. This was the initial motivation for writing Crank, but as I use it more and more, I realize that the main use case for async generators is as a way to race renderings in the tree in Suspense-like fashion, or to consume async iterators which you have already defined elsewhere.

The reality is is that async generator functions have lots of subtle difficulties. It combines both the difficulties of using await and the difficulties of using yield in a single scope, and it’s almost impossible, for instance, to reason about whether your async generator is suspended on a yield or an await. Crank would have been a more or less capable framework if I had only implemented the sync function and sync generator components, and the fact that they render exactly synchronously makes development so much easier.

Yeah I think that's good to know. I assumed that async generators were going to be the Big Thing™ with Crank, but the more I think about async and rendering, the more I realize just how hard the problem is. I guess that's probably why React Suspense is taking so long.

That said, I hope to improve the async generator story soon. I have an async iterator combinator library in the works, which might help us do stuff that looks a little more like FRP.

I'm pretty interested to see what you have planned for this!