7.6 Includes

Includes can be used to import code from a separate file to the current Hollywood script. You can import Hollywood source code (.hws files) as well as Hollywood applets (.hwa files). The code that you import from these external files will be linked into your current project so that these files are not required by compiled Hollywood projects. Importing code is especially useful for bigger projects because it can easily get quite complex to overlook if you have only one source code file with lots of code in it. The idea of include files is to split your program into several pieces. For instance, a jump'n'run game could be split into the pieces Intro, Menu, MapEngine, Level and Game. Now you create source code files for every piece, e.g. Intro.hws, Menu.hws, MapEngine.hws, Level.hws and Game.hws. One of the source code files must be the main source code, that is the source code that you start with Hollywood.

Another use could be to create libraries for Hollywood in the form of Hollywood applets. You could then publish these applets so that other programmers can benefit from them by importing the applet into their own projects. The advantage of publishing your library as a Hollywood applet is that you will not have to expose the source code of your library. Hollywood applets contain only pre-compiled bytecode that is not human readable. So if you want to protect your code but still want to share it with other users, then you can simply publish it as a Hollywood applet.

Let us return to the example of a jump'n'run game now which spreads its code over several files. We assume that Intro.hws will be our main source code because the intro is the first thing, that the end-user will see. Our Intro.hws header will look like the following then:

 
@INCLUDE "Menu.hws"
@INCLUDE "MapEngine.hws"
@INCLUDE "Level.hws"
@INCLUDE "Game.hws"

ShowIntro()
ShowMenu()          ; Function ShowMenu() declared in Menu.hws
RunGame()           ; RunGame() declared in Game.hws
DrawMap()           ; DrawMap() declared in MapEngine.hws
NextLevel()         ; NextLevel() declared in Level.hws

You see that we use the @INCLUDE preprocessor command to include the other four source files in our Intro.hws file. This allows us to call all functions that are declared in those four files from our main source code, i.e. from Intro.hws.

Included files contain only functions, variable or constant declarations in most cases. If there are immediate statements in your include files, e.g. DebugPrint("Hello"), they will be executed before any code from the main source code because all include files are inserted in the order they are declared into the main source code file. In our example from above, Hollywood would first open Menu.hws and insert its code, then MapEngine.hws, then Level.hws and finally Game.hws. So what Hollywood compiles would look like the following:

 
@INCLUDE "Menu.hws"
@INCLUDE "MapEngine.hws"
@INCLUDE "Level.hws"
@INCLUDE "Game.hws"

<...contents of file Menu.hws...>
<...contents of file MapEngine.hws...>
<...contents of file Level.hws...>
<...contents of file Game.hws...>
ShowIntro()
ShowMenu()
...

You see that all include files are inserted before the code section of your main source code file. Therefore all immediate statements will be executed before the code of the main source code too.

If you want to include applets, simply pass an applet file to the @INCLUDE preprocessor command:

 
@INCLUDE "Test.hwa" ; import functions from Test.hwa

LibFunc() ; call LibFunc() which was defined in Test.hwa


Show TOC