Lacewing Help

Can't build for Android, iOS, Mac, HTML5, UWP?

Only Windows is available publicly; Android, iOS, Mac, HTML5, UWP are available only to Darkwire patrons.

Subscribe for $5/mo to get a single platform, or stay longer to get more extensions!

(The liblacewing project and Relay Client/Server was dropped by James in 2015. Blue Client development started in 2012.)

Downloading the public version will only update Windows (and Unicode) variants, not the Android, iOS, Mac, HTML5 or UWP versions.

If you are a patron, update by messaging Phi for the new versions.

You can check which version of those you have by building an app with them, then reading the Lacewing version string expression (client, server).

Windows

Compatibility

Windows Blue Client and Server are limited to Windows XP SP3 and later, like the Fusion runtime.

Using Windows Server 2003 and later should also work.

The CPU usage and RAM usage is tiny.

How to use

For the Fusion editor, Blue Client and Server expect to have internet access when Fusion starts up.

If Fusion is closing instantly when you put a Blue Client/Server in frame, try running the UC Tag Fix Tool.

For built EXEs, the only thing that might need changing is giving access for the Blue app past the firewall(s). You should get a popup when you start connecting or hosting from a Blue app, but if not, go into the antivirus or firewall settings to add the EXE as allowed, or as an exception.

For Blue Client, read the Guides > Examples topic.

For Blue Server, read the Guides > Hosting a server topic, and if you're hosting for HTML5 and/or UWP, read the Guides > Hosting a server > Hosting a WebSocket server topic afterwards.

Android

Compatibility

Android Blue Client and Server are limited to Android OS v4.4.4 (KitKat, June 2014), or later, all the way to the latest Android beta.

Find your OS version under your Settings app, under About Phone.

Lacewing Android Relay Client is compatible with Android OS v6.0 (Oct 2015) and earlier. It is not recommended that you use Lacewing Relay Client, for Android or other platforms; use Lacewing Blue Client instead.

How to use

For both Blue Client and Blue Server, you should activate the INTERNET permission in Android app properties to use them.

If you don't have INTERNET activated, Blue Client and Server will detect it and create a pop-up message, and attempt to abort the build with a SAXParseException.

• There are no extra steps needed for Android Blue Client.
  You may want to read Guides > Examples for example Fusion code, including screenshots, videos, and MFAs.
• For Android Blue Server, if you are not hosting for HTML5 or UWP clients, then there are no extra steps needed.
  You may want to read Guides > Hosting a server for how to get IP addresses of your server, how to set up a domain, etc.
  If hosting for HTML5 and/or UWP clients, you should then read Guides > Hosting a server > Hosting a WebSocket Server.

iOS

Compatibility

iOS Blue Client and Blue Server are limited to devices running iOS 10.0 (Sept 2016) or later, all the way to latest iOS beta.

This translates to iPhone 5 (all types), iPad 4th generation, iPad Air, iPad Pro, iPod Touch 6th generation, and all later devices.

You can also use Blue in an Xcode simulator for a device running iOS 10.0 or later.

Note that Lacewing Relay Client is not compatible with iOS, only Blue.

How to use

For both Blue Client and Blue Server, you need to do extra steps so your Fusion Xcode project links to the Blue extension files. This process should take only a minute or two.

Fusion includes the files in the built Xcode project zip file, but doesn't link them in the Xcode project. To link them, there is two sets of files to include:

First, add the Blue Client and/or Blue Server code files. These go under Classes\Extensions:

The files should be highlighted if they're not already linked:

When linking them, make sure your project is checked to add to target for the project.

• For Blue Client, add the three CRunBluewing_Client files.

• For Blue Server, add the three CRunBluewing_Server files.

Next, link the C++ libraries containing the code. These go under Frameworks:

• For Blue Client, add the Frameworks/Bluewing_Client.xcframework folder.
  Select the xcframework itself, not the files within it, as the screenshot shows.
• For Blue Server, add the Frameworks/Bluewing_Server.xcframework file, the Frameworks/libcrypto.a and the Framework/libssl.a files.
  The second two are for secure WebSocket server's encryption, and because using them is part of Blue Server, they're required for Xcode even if you don't use secure WebSocket.
• Note that if you want to not use either Blue extension, Fusion still #includes them in iOS Development builds, as it does to all iOS extensions.
• You will need to remove the #include and the "new CRunBluewing_Client/Server" from Classes\Extensions\ExtLoad.m to exclude a Blue object from your iOS project – same as other iOS extensions you don't want.
  You don't need to, but you can delete the unlinked extension files and libraries from the hard drive as well.

You will have to repeat these steps if you build your Xcode project again. But you can rebuild an iOS application (cci) file by itself – which contains Fusion events, images, etc – without having to rebuild the whole Xcode project and needing to repeat these steps. Change the Fusion project build type.

• There are no extra steps needed for iOS Blue Client.
  You may want to read Guides > Examples for example Fusion code, including screenshots, videos, and MFAs.
• For iOS Blue Server, if you are not hosting for HTML5 or UWP clients, then there are no extra steps needed.
  You may want to read Guides > Hosting a server for how to get IP addresses of your server, how to set up a domain, etc.
  If hosting for HTML5 and/or UWP clients, you should then read Guides > Hosting a server > Hosting a WebSocket Server.

Mac

Compatibility

Mac Blue Client and Blue Server are limited to devices running Mac OS X 10.13 (High Sierra) or later, all the way to latest Mac beta. ARM64 and x86_64 Mac is supported.

Note Mac OS for ARM64 starts at Mac OS 11.0 (Big Sur).

Mac OS 10.12 can also be supported by Blue, but Fusion's latest beta creates apps limited to Mac OS 10.13+ anyway.

How to use

To build apps, there are no extra steps.

• There are no extra steps needed for Mac Blue Client.
  You may want to read Guides > Examples for example Fusion code, including screenshots, videos, and MFAs.
• For Mac Blue Server, if you are not hosting for HTML5 or UWP clients, then there are no extra steps needed.
  Note when starting to host the Mac Blue server, you will get a popup notification from the firewall, asking for approval.
  You may want to read Guides > Hosting a server for how to get IP addresses of your server, how to set up a domain, etc.
  If hosting for HTML5 and/or UWP clients, you should then read Guides > Hosting a server > Hosting a WebSocket Server.

You may have to link the extension bundles if creating a Mac xcodeproj build. It should be included as part of your project, but not necessarily automatically linked. Read the above iOS section for the idea on how to add the bundle like a framework.

HTML5

Compatibility

Lacewing Blue HTML5 Client uses plain WebSocket technology to run in browsers.

WebSocket is compatible with browsers from 2012 and later, including Chrome, Firefox, Opera, Safari, Edge, etc.

It is compatible with nearly all mobile browsers, including Android and iOS built-in browsers; it is not compatible with Opera Mini, but it is compatible with Opera Mobile.

It is compatible with Internet Explorer 10 and later.

It is compatible with lesser-known Asian browsers like QQ browser, Baidu browser and KaiOS browser.

Note that while Blue Client may be compatible with these, it is not obvious if the Fusion HTML5 runtime itself is.

For more details on compatibility, visit CanIUse for WebSockets.

Blue HTML5 Server, as in a HTML5 Blue Server object, cannot exist, as there is no standard internet technology for HTML5 webpages hosting their own servers.

The closest you get to a server in JavaScript is not browser JavaScript, but something non-browser like Node.js, which is a whole runtime environment, as Java runtime environment is… and that's not useful for a Fusion HTML5 app that runs on a browser JavaScript only.

All Blue Server platforms are capable of serving to a HTML5 client, though. See Guides > Hosting a server > Hosting a HTML5 server for details.

How to use

To build apps, Lacewing Blue HTML5 Client has no extra steps.

However, when using the client, note a few things:

First, Blue HTML5 Client uses fake-UDP. 

The Blue HTML5 server translates intended UDP messages into TCP and sends them to Blue Client to trigger Blasted events instead of Sent.

It is also supported in reverse; HTML5 Blue Client Blasted actions will still be sent over TCP, but will be translated to and forwarded as UDP by Blue Server if the receiving client is not HTML5. So all platforms will seem to support UDP, with HTML5 having no obvious difference.

So you should not need to re-code your message events, but be aware the limitations of TCP apply to the UDP messages for HTML5 clients. See Types of messages > Sending versus Blasting topic for limitations and how TCP/UDP differ.

Second, there are two HTML5-compatible WebSocket servers, one encrypted and one plain text; make sure you are connecting to the right port.

Both WebSocket servers use the WebSocket protocol, not raw socket like the regular Relay server, so a client expecting WebSocket will not be able to use a raw socket Relay server, and vice versa.

This means, effectively, there are three servers in Blue Server object. Connecting to the wrong type will not work, and may result in a frozen connection that takes too long to abort.

In HTML5 clients, you can manually specify the secure or insecure version of WebSocket by connecting to "wss://server:port/" instead of "server:port" in the client's Connect action. Simply specify "ws://" for insecure, and "wss://" for secure.

Without specifying, if your HTML5 client is running from a HTTPS webpage, it will default to secure WebSocket. If running from a HTTP webpage, it will default to insecure.

But, if you connect to port 443, the HTTPS default port, it will default to secure again.

Servers are recommended to use either the default ports, if not hosting a website on the same server, or to use something completely different (like ports 6122 and 6123 to go with normal Relay 6121).

Note that some ports are restricted on server platforms. For more detail, read your server platform notes above.

If you connect to a secure WebSocket server, the data passed in the connection is encrypted with the same technology as a HTTPS browser connection. This happens invisibly, and it means if anyone is listening into your connection along the route, they cannot read the data.

This does not mean the server isn't evil, although to the creator's knowledge there are no security weaknesses in Blue HTML5 Client for an evil server owner to exploit.

Use of the secure port is required on https:// webpages. Web browsers will refuse to connect to an insecure WebSocket port from a secure webpage, for security reasons.

Third, Bluewing Client loads text encoding, zlib and grapheme counting scripts from GitHub via JSDelivr service, if the features are not detected in the browser.

Some browsers will detect this external script loading as a XSS attack (cross-site scripting attack), the browsers seeing it as suspicious as an advert downloading external [virus] scripts that weren't in the original advert.

It is recommended for both speed of page loading, and to prevent being blocked as XSS or due to bad CORS settings, that you download these scripts yourself, and add them as <script> tags inside the <head> tag before Fusion runtime loads.

As an extra point, the HTML5 Client's Convert string to UTF-8 and count visible chars (graphemes) expression uses the Intl.Segmenter browser feature to count visible characters in text (graphemes).

Firefox does not have this feature, so if you want to use this with proper compatibility, it's recommended you grab the grapheme-splitter.js file as well and load it beforehand.

If the browser lacks a feature and external scripts fail to be loaded, an error will be created when you use them.

The files you need will be seen in the head tag, if you use Inspect Element on a running Blue Client HTML5 app. But for completeness:

• Text encoding from JavaScript's UTF-16 from/to Bluewing's UTF-8:
  Built into most browsers except Internet Explorer and Opera Mini, where it will be downloaded by Blue.
  https://cdn.jsdelivr.net/gh/inexorabletash/text-encoding@master/lib/encoding.min.js
• Zlib compression/decompression.
  Loaded in every browser, as no browser supports zlib natively.
  https://cdn.jsdelivr.net/gh/imaya/zlib.js@master/bin/zlib.min.js
• UTF-8 grapheme counting:
  Built into most browsers as Intl.Segmenter, but missing in Firefox and some other browsers. Used for the Convert string to UTF-8 and count visible chars (graphemes) expression only.
  https://cdn.jsdelivr.net/gh/orling/grapheme-splitter@master/index.js
  
  

It should be noted there are three exported JS functions from the HTML5 Blue Client extension. If you have the Bluewing_Cllient variable, you can call:

• blueClient['GetRecvMsg']() – takes no parameters, returns an ArrayBuffer
• blueClient['GetSendMsg']() – takes no parameters, returns a Uint8Array
• blueClient['SetSendMsg'](uint8Array) – takes a Uint8Array, returns void

You should call them with bracket notation as shown above, as Fusion's HTML5 Final build will minify dot notation and potentially break the function call.

Lacewing Blue HTML5 Server… that is, a Blue Server hosting from a HTML5 app – can not exist. See Compatibility above for why.

UWP

Compatibility

UWP projects built by Fusion use JavaScript, and so UWP clients use a browser-like interface. So far, it has only been tested for UWP on Windows, but compatibility is expected to all that HTML5 Clients can run on.

See above notes about HTML5 compatibility for more information on WebSocket support.

Be aware that UWP Blue Client-using apps will not be approved by Microsoft within the Xbox Live Creator Program, as per the Program's terms, no direct play or chat is allowed.

Games using those features must be released within the ID@Xbox program instead.

Blue UWP Server, as in a UWP Blue Server object, doesn't exist, and is unlikely to, as Fusion produces JavaScript-based UWP apps.

While UWP apps can also be built with C++ and C#, the Fusion runtime doesn't do it. JavaScript inside UWP is browser JS, which doesn't allow hosting servers. To host a server, the C++/C# side of UWP must be invoked from the JavaScript project – if that's even possible.

So don't expect a UWP Blue Server.

How to use

To build apps, Lacewing Blue UWP Client has no extra steps.

However, when using the client, note a few things:

First, Blue UWP Client uses fake-UDP.

UDP messages are actually sent and received over TCP, but will trigger Blasted events.

To see more about that, see the notes about HTML5 Client above.

Second, UWP Blue Client uses WebSocket connections, the same as HTML5 Blue Client, so do not connect to the regular Relay servers as the connection will fail.

As described in HTML5 client "How to use" section above, you can use the "ws://" and "wss://" explicit protocol type, but since UWP apps don't run in https by default, you do not need the secure WebSocket, so you don't need a TLS certificate to support UWP clients.

However, using the insecure WebSocket variant does still expose your data as much as using it in a HTML5 client.

UWP Fusion apps are set to allow internet connections in project properties by default, using the Internet (Client) setting under the package.appxmanifest file.

Don't disable this setting, for obvious reasons.

Third, three JavaScript files that are normally downloaded in the HTML5 runtime are included by default in the UWP app, including the UTF-8 visible char script.

The three scripts (zlib.min.js, encoding.min.js, grapheme-splitter.min.js) are put in Data\Runtime\Wua\js\runtime\libs folder, and are added to the webpage in the modified Fusion runtime script file Data\Runtime\Wua\js\default.js.

For those making advanced apps, it should be noted there are three exported JS functions from the UWP Blue Client extension. If you have the Bluewing_Cllient variable, you can call:

• blueClient['GetRecvMsg']() – takes no parameters, returns an ArrayBuffer
• blueClient['GetSendMsg']() – takes no parameters, returns a Uint8Array
• blueClient['SetSendMsg'](uint8Array) – takes a Uint8Array, returns void

You should call them with bracket notation as shown above.

Lacewing Blue UWP Server… that is, a Blue Server hosting from a UWP app – is unlikely to exist. See Compatibility above for why.

(Note there are port limitations – port 1025 to 49000 or so, should it exist.)