HSP : HSP3Dish / onion software 2021(c)

hsp3dish.js (WebGL / html5 version)

Programming Guide

1. hsp3dish.js Overview
2. How hsp3dish.js works
3. Conversion by HSP3Dish Helper
4. Run on browser
5. Display size scaling
6. Play media files
7. Browser control by exec, dialog command (New!)
8. Restrictions / Known Problems
9. Future plans
10. License / Acknowledgments

hsp3dish.js overview

hsp3dish.js is a HSP3Dish runtime that runs on a web browser that supports WebGL. It is possible to reproduce the functions supported by HSP3Dish for Windows on many web browsers. This makes it possible to run on various operating systems such as MacOS and Linux as well as Windows, and it will be possible to easily execute HSP applications without the hassle of installation.
In this manual, we will explain how to use the hsp3dish.js version and points to note.

A WebGL-enabled browser is required for operation. We have confirmed the operation in the following environment.

• Chrome
• Firefox
• Safari
• Internet Explorer 11
• Microsoft Edge
• Firefox Mobile Browser (Android)

HSP3Dish Helper tools are included to assist in converting HSP3Dish scripts. This makes it possible to convert for hsp3dish.js relatively smoothly. (In addition, in order to check the operation, you need a homepage that you can upload or a WEB server that operates locally.)

How hsp3dish.js works

hsp3dish.js is llvm compiler and Emscripten , This is a conversion of the HSP3 runtime for JavaScript and WebAssembly. Since it is based on the original source of HSP3, the system is highly compatible in operation and easy to update.
The iOS version and android version of HSP3Dish are executed after converting the HSP script to native code. hsp3dish.js operates as an interpreter (sequential execution) based on the HSP script output to the intermediate code (.ax object file). This is the same program as the Windows version of HSP3Dish and is extremely compatible.
The execution speed of the script depends on the CPU speed of the machine running the browser and the speed of the VM, but if it is a recent PC, it will work within a practical range.

Conversion by HSP3Dish Helper

Launch HSP3Dish Helper (hsp3dh.exe) in the HSP installation folder (must be updated with the latest version of the HSP3Dish development set).

Press the "hsp3dish.js" button lined up below to switch to hsp3dish.js conversion mode. You should see something like the one above.
By setting the required information in this dialog and pressing the "Convert" button, all the files required for operation on the web browser will be created. The items to be set in the dialog are as follows.

• Source script



Specify the HSP script (.hsp) to convert. It must be a script written for HSP3Dish. You can open the file selection dialog by pressing the "Browse" button.
Be sure to use "File name with only half-width alphanumeric characters (do not use Japanese (full-width))" for the script file name.
The generated screen size uses the settings in the hsp3dish.ini file located in the same folder as the source script. For the settings of the hsp3dish.ini file, refer to the "About the startup setting file" section.

• Data folder



The data folder is for preparing files (including image data, sound data, etc.) to be read in the script, such as the picload command and bload command.
The "data" folder under the folder specified in "Source Script" is recognized as a data folder. Store the files read from the script together in the data folder.
All files that contain a data folder are packed as data files (with a .data extension). If unnecessary files are included, it will waste space, so be sure to put only the necessary files.
Be sure to "File names with only half-width alphanumeric characters (do not use Japanese (full-width))" for the files included in the data folder. Also, only the specified data folder will be searched, and subfolders will not be included. If you do not need the data file, you can leave it blank.

• Memory size



You can set the upper limit of the memory block allocated when the browser is executed. If left blank, the default value (200 MB) will be used. Normally, the default value is fine, but if you have a large script or a large amount of data, specify a value greater than 100. (If you specify 500, it will be 500 megabytes.)
(If the hsp3dish.js console displays "Cannot enlarge memory arrays." When running the browser, try adjusting the upper limit of the memory block.)

• Use HGIM G4



Convert HGIMG4 scripts. "Hsp3dish-gp.js" is required at the time of execution.
Place the data used by HGIMG4 in "res" and "res / shaders" under the folder specified in "Source Script". (Located in sample / hgimg4)
* Please note that the off-screen drawing commands used for post effects etc. cannot be used in the current version.

• Use WebAssembly



Convert to WebAssembly format. An additional ".wasm" file is required at runtime.
By using the WebAssembly format, you can expect speedup of reading and execution speed. However, due to limited support for web browsers, it is still an experimental implementation.

• Output debug information



Generates data including debug information when converting the script.
By outputting debug information, when an error occurs during execution on the browser, You can refer to the line number and the file name of the source script. If you don't know where the error occurred when running the browser, try printing out the debug information and checking.

After completing the settings, click the "Convert" button. At that time, you can select the type of html template in the combo box above. Now you can choose between standard html (white background) and html with a black background.
The conversion will generate scripts and data files for hsp3dish.js.
The generated files are as follows.

• (source script name) .html file
• (source script name) .data file
• hsp3dish.js file (hsp3dish-gp.js when using HGIMG4)
• hsp3dish.wasm file (hsp3dish-gp.wasm when using HGIMG4)

These files should have been generated in the folder where the original source script is located. (For example, if you convert block3.hsp, block3.html and block3.data will be generated.)
Simply upload the file generated here on the WEB and it can be executed on the WEB browser.
The .html file is an HTML file that can be opened from a web browser. For example, if you upload to the location "www.onionsoft.net/hsp/hsp3js/" "Http://www.onionsoft.net/hsp/hsp3js/block3.html" is the URL for execution.
A .data file is a data file that is read from JavaScript in an HTML file and contains all the data needed to run it.
The "hsp3dish.js" and "hsp3dish-gp.js" files are the core of the HSP runtime and are required to run HSP3Dish on the WEB. This is the same for all scripts, so even if you have multiple .html and .data in the same folder, they can be shared.
If you convert to WebAssembly format, an hsp3dish.wasm file (hsp3dish-gp.wasm when using HGIMG4) will be generated. (Normally not generated) Upload this file to the server as well as "hsp3dish.js".

Run on browser

By uploading the .html file, .data file, and hsp3dish.js file generated from HSP3Dish Helper on the WEB, you can execute it on the browser. Opening a local .html file does not start it. Be sure to install the file on the WEB server.
From this page , actually check the operation of the block3.hsp script. I can.
The html file generated by default has "Resize Cavas", "Lock / hide mouse pointer" checkboxes, and "Full screen" buttons. ..
In addition, the console (system message display area) of hsp3dish.js is placed at the bottom of the execution screen.
The user is free to modify the html file. Please adjust the layout, layout, etc. as you like.

Display size scaling

By editing the html file, you can set the display size, scaling and other settings. Open the generated .html file with a text editor and edit the following location.

	    Module.preRun.push(function() {
ENV.HSP_WX = "480"; // Script operating resolution
	        ENV.HSP_WY = "800";
ENV.HSP_SX = "480"; // Display resolution
	        ENV.HSP_SY = "800";
ENV.HSP_AUTOSCALE = "0"; // Scaling mode
ENV.HSP_FPS = "0"; // Frame rate
ENV.HSP_LIMIT_STEP = "15000"; // Number of execution steps until processing is returned to the browser
	    });
	

The numerical values ​​specified in "ENV.HSP_WX" and "ENV.HSP_WY" are the operating resolution sizes (X, Y) of the script. This is set to the value obtained from the hsp3dish.ini file during the script conversion.
The numerical value specified by "ENV.HSP_SX" and "ENV.HSP_SY" is the resolution size (X, Y) actually displayed on the WEB browser. If the operating resolution and display resolution of the script are different, the setting for scaling (enlargement / reduction) will be the "ENV.HSP_AUTOSCALE" item. "0" is specified by default, but the following values ​​can be set.

0: Optimal size that fits on the entire screen (aspect ratio is maintained)
1: Scale based on the size in the X direction (aspect ratio is maintained)
2: Scale based on the size in the Y direction (aspect ratio is maintained)
3: Ignore the aspect ratio and display it on the entire screen
	

Other options can also be set as follows.
Specify a fixed frame rate with "HSP_FPS". If it is 30, it will be updated at 30 FPS (30/1000 seconds). If 0 (default), leave the number of frames to the browser (requestAnimationFrame).
"HSP_LIMIT_STEP" specifies the number of execution steps until the process is forcibly returned to the browser. "15000" is specified by default. Please note that if it is too large, the browser will stop responding when there is a problem with the script or processing system.

Playing media files

The current version has experimental support for playing media files.

-Supports wav and mp3 format playback (mmload, mmplay instructions)
-The ogg format is supported only by some browsers (mmload, mmplay instructions)
・ We have confirmed the operation on Chrome and Firefox.
-It does not work on IE11 (it does not cause an error)
・ Does not support mci instructions
・ Does not support video playback
	

The formats that can be read by the mmload instruction are ".wav", ".mp3", and ".ogg".
Since media files can be huge as resources, current resource management, which reads everything into memory at startup, is not suitable for playing a large number of songs. We would like to improve this point in future versions.

Browser control by exec, dialog command

The dialog command allows you to display a standard browser dialog. (Common dialogs other than standard dialogs are not supported)
The exec instruction allows you to control the browser at a finer level. The normal exec instruction is a function for calling OS commands, In hsp3dish.js, it has the role of executing JavaScript code directly.

		exec "alert('TEST');"
	

This allows you to call the functions of JavaScript from within the HSP script. However, if an error occurs in the JavaScript syntax, it may stop due to a browser error. Please note that there is.
You can specify the URL of the newly opened page by specifying 16 as the option value of the exec instruction.

		exec "https://hsp.tv",16
	

In this example, the URL "https://hsp.tv" is newly opened in the browser.
By using the exec command, you can open a WEB page in cooperation with the program on the HSP side. Processing such as changing the display of the browser becomes possible.

Restrictions / Known Problems

The current version has the following restrictions: Other functions are basically the same as HSP3Dish.

・ Media-related functions (limited by browser and file type)
・ HGIMG4 off-screen drawing command is not supported
・ DPM files cannot be used
-Files such as the bsave command cannot be saved statically.
	

In addition, the following have been reported as known issues.

-Multimedia related instructions do not work in IE11
	

In addition, since it is running on a web browser, different actions and displays may occur. Currently, data files are read in bulk, so large applications (such as using a lot of images) can use it. Please note that it may become heavy or cannot be processed.

Future plans

hsp3dish.js will continue to expand its functions as an environment for easily executing HSP on the WEB. The following are the functions that we are considering in future version upgrades. In future versions, we want to aim for higher compatibility and improved functionality.

-Implementation of network extension processing
・ Linkage function with SoupSeed
・ Code editing and compilation execution on the WEB
	

License / Acknowledgments

Users can use hsp3dish.js / hsp3dish-gp.js with license similar to HSP3Dish (BSD license) . The following license notation is included in the file, so please upload it to the homepage as it is without modifying the hsp3dish.js / hsp3dish-gp.js file. There is no obligation to display information about the license or author anywhere else. In addition, no license fee is required for commercial or non-commercial use.

When using hsp3dish.js / hsp3dish-gp.js by linking directly, "http://www.onionsoft.net/hsp/v36/hsp3js/hsp3dish.js" "http://www.onionsoft.net" Please use "/hsp/v36/hsp3js/hsp3dish-gp.js". (However, please note that the contents are subject to change if there is a problem with operation such as when a high load occurs or there is a security concern.)

	Copyright (C) 1997-, Onion Software/onitama.
	Copyright (C) 2014-, zakki, K-s.
	All rights reserved.

	Redistribution and use in source and binary forms, with or without
	modification, are permitted provided that the following conditions are met:

	Redistributions of source code must retain the above copyright notice, this
	list of conditions and the following disclaimer.  Redistributions in binary
	form must reproduce the above copyright notice, this list of conditions and
	the following disclaimer in the documentation and/or other materials provided
	with the distribution.  Neither the name of the Onion Software nor the names
	of its contributors may be used to endorse or promote products derived from
	this software without specific prior written permission.

	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
	LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	POSSIBILITY OF SUCH DAMAGE.
	

hsp3dish.js / hsp3dish-gp.js was created based on the Emscripten version of HSP3Dish implemented by zakki . is. K-s cooperated in improving the multimedia function and drawing function. We would like to thank Mr. zakki for developing a wonderful system and many people who gave us their opinions.
The Emscripten version of HSP3Dish is a derivative of OpenHSP. The source code can be obtained from the OpenHSP repository.

		OpenHSP Development
		http://dev.onionsoft.net/trac/openhsp/

Emscripten version of HSP3 Dish WiKi
		http://dev.onionsoft.net/trac/openhsp/wiki/DirTrunk/Hsp3dish/Emscripten

		zakki
		https://twitter.com/k_matsuzaki
	

• Return to top of this page
• Return to index