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.
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
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
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
Level.hws and finally
Game.hws. So what Hollywood compiles would look like
@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