vc64webplayer - vc64web/virtualc64web GitHub Wiki

this tutorial explains how to embed the emulator on your own website.

to make this as easy and non-invasive as possible, we created a separate component next to the vc64web itself, which renders an iframe over an existing HTML element of your own webpage for example an image element and loads the emulator into it. Or in other words the vc64webplayer can exchange an existing HTML element of your webpage for example a <div> or <img> element with an <iframe> element in which it then loads the emulator.

This technique allows you to embed vc64web into an existing HTML page without even serving any emulator file at all.

How does it work? Give me a recipe!

Well, to integrate the player into your webpage follow three steps

(1) add a reference to the vc64web_player.js file

locate the end of the <head> element of your webpage and insert the following script element

<script src="https://vc64web.github.io/js/vc64web_player.js"></script>

this will include the functionality to spawn the emulator into an element of your web page

(2) add styles right after the script element and modify colors to your needs

<style>
        #player_container {
            background-color: black;
        }
        #vc64web {
            border:none;
        }
        .player_icon_btn {
            background-color: transparent;
            color: white;
            margin-right: 15px;
            cursor: pointer;
        }
        .btn_play {
            color: #2575ff;
            cursor: pointer;
        }
</style>

(3) locate the element in which the player has to be rendered into ...

<-- image to be exchanged -->
<img id="my_preview_pic_123" src="..." />

we want now to load the emulator into the aboves pics screen space when the visitor clicks the image

we do this by adding a onclick=" ... do some stuff ..." attribute to the image element

<img 
  id="my_preview_pic_123" 
  src="..." 
  onclick="
    vc64web_player.load(
       this, 
       '#openROMS=true#navbar=hidden#wide=true#border=0.3#port2=true', 
       'http://vc64web.github.io/doc/media/wolfling14.prg'
    );
    return false;
  " 
/>

lets try this example in a browser

https://vc64web.github.io/doc/wiki/player_example.html

that was the most straight forward integration. The joystick port 2 has been linked to the cursor direction keys and the space key for joystick fire. (hint: You can try yourself when saving that html page on your filesystem editing it as you like and open it with your browser.)

also take a look at all possible preconfig items at simple preconfiguration

But but but what about my iPhone? And what about touchscreen devices ?

Here we want to be able to control with a virtual joystick on the touch surface.

Let's do ...

strategy: we need to know whether we have been asked to start the player by a touch or a mouse click

we do this by adding a ontouchstart="... do some stuff..." attribute to the image element

<img 
  id="my_preview_pic_123" 
  src="..." 
  ontouchstart="touched=true"
  onclick="
    let touch=(typeof touched!='undefined')?touched:false;
    touched=false;
    let config=
    {
      touch:touch,
      openROMS:true,
      navbar:false,
      wide:true,
      border:0.3,
      port2:true,
      url:'http://vc64web.github.io/doc/media/wolfling14.prg'
    }; 
    vc64web_player.load(this,encodeURIComponent(JSON.stringify(config)));
    return false;
  "		
/>

BTW: we just used the JSON notation for preconfig instead of the simple hashtag notation the JSON notation is described in preconfig with JSON notation

lets try the touchscreen sensitiv version now on a touchscreen browser

https://vc64web.github.io/doc/wiki/player_example2.html

It does not load my c64-program 😱!

... then you probably have been stopped by the browser police 👮

Modern browsers implement security policies, which prevent javascript out of the box to load resources from different adresses (they call it origins).

Fortunately the player can start any title in the csdb.dk, although they are resident on a different origin. This works because the guys at csdb explicitely granted us CORS (Cross Origin Resource Sharing).

But when you want to load the c64 app from your own site its likely that it is not granted yet. That is because vc64web is likely loaded from a different origin than your webpage.

First it is easy to grant CORS if you can alter the http-response header when serving the c64 program.

Access-Control-Allow-Origin: *

or

Access-Control-Allow-Origin: https://vc64web.github.io/

Also if your webpage is hosted at github.io then these headers are set by default. Hosting a website at github.io with gh-pages is free for github users.)

Alternate ways of loading a c64 program from your site without need of CORS.

If you can not grant CORS then there is another way to load an arbritary program into the emulator from your own web page.

It is possible to simply load a same site stored c64 app, e.g. your webpage loads the program from your site and passes it into the emulator after it has been started.

This technique (I call it "iFrame ressource injection technology" IFRIT) is supported by vc64web ...

you just have to create a file descriptor

let my_file={
  url:'https://my-c64-website.de/wolfling14.prg',
  name:'samesite_wolfling.prg'
};

and then pass it to the player before you call load, like this ...

vc64web_player.samesite_file=my_file;

lets use the samesite loading for our example

<img 
style="width:60vw" src="../images/wolfling.gif" 
ontouchstart="touched=true"
onclick="
  let touch=(typeof touched!='undefined')?touched:false;
  touched=false;
  let config=
  {
    touch:touch,
    openROMS:true,
    navbar:false,
    wide:true,
    border:0.3,
    port2:true
  };
  vc64web_player.samesite_file=
  {
    url:'https://vc64web.github.io/doc/media/wolfling14.prg',
    name:'samesite_wolfling.prg'
  };
  vc64web_player.load(this,encodeURIComponent(JSON.stringify(config)));
  return false;
"		
/>

the difference is that the c64 program is now loaded from the javascript of your own website (the referenced player) rather than from the javascript of the website where the vc64web emulator is hosted (the different origin).

lets try this now in a browser

https://vc64web.github.io/doc/wiki/player_example3.html

I can not upload files ... I can only edit my HTML page ...

What if you are in the poor situation that you can write html but you can not upload any c64 file to your webserver ? Well we thought on that case too.

you can have a binary file descriptor

vc64web_player.samesite_file={
  bin: Uint8Array.from(something),
  name:'samesite_wolfling.prg'
};

or you can pass a base64 file descriptor

vc64web_player.samesite_file={
  base64: 'AQgLCB4AnjIwNjEAAACgAHipAI2RA...3z2Z3t2srQ71hMQg3M8g==',
  name:'samesite_wolfling.prg'
};

see the example for passing a binary program https://vc64web.github.io/doc/wiki/player_example4.html

and here the example for passing a c64 programm encoded in a base64 string https://vc64web.github.io/doc/wiki/player_example5.html

something still unclear or not working ? get in touch with us...

If you have mastered this chapter then you might be interested in the next chapter

preloading the web player with your specific system roms

⚠️ **GitHub.com Fallback** ⚠️